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preface 





I first encountered Python in 1993 when I joined a small company in Rhode Island. Their pri- 
mary product was a GUI-builder for X/Motif that generated code for C, C++, Ada and Python. I 
was tasked with extending the object-oriented interface for X/Motif and Python. In the past I'd 
become skeptical about the use of interpretive languages, so I began the task with little excite- 
ment. Two days later I was hooked. It was easy to develop interfaces that would have taken much 
more time and code to develop in C. Soon after, I began to choose interfaces developed using the 
Python interface in preference to compiled C code. 

After I left the company in Rhode Island, I began to develop applications using Tkinter, 
which had become the preeminent GUI for Python. I persuaded one company, where I was 
working on contract, to use Python to build a code-generator to help complete a huge project 
that was in danger of overrunning time and budget. The project was a success. Four years later 
there are many Python programmers in that company and some projects now use Tkinter and 
Python for a considerable part of their code. 

It was this experience, though, that led me to start writing this book. Very little documenta- 
tion was available for Tkinter in the early days. The Tkinter Life Preserver was the first document 
that helped people pull basic information together. In 1997 Fredrik Lundh released some excel- 
lent documentation for the widget classes on the web, and this has served Tkinter programmers 
well in the past couple of years. One of the problems that I saw was that although there were sev- 
eral example programs available (the Python distribution contains several), they were mostly brief 
in content and did not represent a framework for a full application written with Tkinter. Of 
course, it is easy to connect bits of code together to make it do more but when the underlying 
architecture relies on an interpreter it is easy to produce an inferior product, in terms of execu- 
tion speed, aesthetics, maintainability and extensibility. 

So, one of the first questions that I was asked about writing Tkinter was “How do I make an 
XXX?” Td usually hand the person a chunk of code that I'd written and, like most professional 
programmers, they would work out the details. I believe strongly that learning from full, working 
examples is an excellent way of learning how to program in a particular language and to achieve 
particular goals. 

When I was training in karate, we frequently traveled to the world headquarters of Shuko- 
kai, in New Jersey, to train with the late Sensei Shigeru Kimura. Sensei Kimura often told us “I 
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can't teach you how to do this (a particular technique)—you have to steal it.” My approach to 
learning Tkinter is similar. If someone in the community has solved a problem, we need to steal 
it from them. Now, I am not suggesting that we infringe copyright and professional practice! I 
simply mean you should learn from whatever material is available. I hope that you will use the 
examples in the book as a starting point for your own creations. In a small number of cases I have 
used code or the ideas of other programmers. If this is the case I have given the original author an 
appropriate acknowledgment. If you use one of these pieces of code, I'd appreciate it if you would 
also acknowledge the original author. After all, what we “steal” has more value than what we pro- 
duce ourselves—it came from the Sensei! 

I was impressed by the format of Douglas A. Young’s The X Window System: Programming 
and Applications with Xt. It is a little old now, but it had a high proportion of complete code 
examples, some of which made excellent templates upon which new applications could be built. 
Python and Tkinter Programming has some parallels in its layout. You will find much longer 
examples than you may be accustomed to in other programming books. I hope that many of the 
examples will be useful either as templates or as a source of inspiration for programmers who 
have to solve a particular problem. 

One side effect of presenting complete examples as opposed to providing code fragments is 
that you will learn a great deal about my style of programming. During the extensive reviews for 
Python and Tkinter Programming some of the reviewers suggested alternate coding patterns for 
some of the examples. Wherever possible, I incorporated their suggestions, so that the examples 
now contain the programming styles of several people. I expect that you will make similar 
improvements when you come to implement your own solutions. 

I hope that you find Python and Tkinter Programming useful. If it saves you even a couple of 
hours when you have an application to write, then it will have been worth the time spent reading 


the book. 
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graphical user interfaces (GUIs) to their applications. Because Python and Tkinter Programming 
presents many fully functional examples with lots of code annotations, experienced programmers 
without Python expertise will find the book helpful in using Python and Tkinter to solve imme- 
diate problems. 

The book may also be used by Tcl/Tk script programmers as a guide to converting from 
Tcl/Tk to Python and Tkinter. However, I do not intend to get into a philosophical discussion 
about whether that would be a proper thing to do—I’m biased! 
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conventions 





Example code plays a very important role in Python and Tkinter Programming. Many program- 
ming books feature short, simple examples which illustrate one or two points very well—but 
really do little. In this book, the examples may be adapted for your own applications or even used 
just as they are. Most of the examples are intended to be run stand-alone as opposed to being run 
interactively. Most examples include markers in the body of the code which correspond to expla- 
nations which follow. For example: 


def mouseDown(self, event): 
self.currentObject = None ® 
self.lastx = self.startx = self.canvas.canvasx(event.x) 
self.lasty = self.starty = self.canvas.canvasy(event.y) 
if not self.currentFunc: 
self.selObj = self.canvas.find_closest(self.startx, eo 
self.starty) [0] 
self.canvas.itemconfig(self.selObj, width=2) 


self.canvas.lift(self.selObj) 





Code comments 


The mouseDown method deselects any currently selected object. The event returns x and y coordi- 
nates for the mouse-click as screen coordinates. The canvasx and canvasy methods of the 
Canvas widget ... 


If no drawing function is selected, we are in select mode and we search to locate the nearest 
object on the canvas and select it. This method of ... 


Occasionally, I have set portions of code in bold code font to highlight code which is of 
special importance in the code example. 

In a number of examples where the code spans several pages I have interspersed code expla- 
nations within the code sequence so that the explanatory text appears closer to the code that is 
being explained. The marker numbering is continuous within any given example. 
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All source code for the examples presented in this book is available from the Mannng web- 
site. The URL www.manning.com/grayson includes a link to the source code files. 
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PART 





Basic concepts 


I, part 1, [Il introduce Python, Tkinter and application programming. Since I assume youre 
already somewhat familiar with Python, chapter 1 is intended to illustrate the most important features 
of the language that will be used throughout the book. Additionally, I'll discuss features of Python's 
support for object-oriented programming so that those of you familiar with C++ or Java can under- 
stand how your experience may be applied to Python. 

Chapter 2 quickly introduces Tkinter and explains how it relates to Tcl/Tk. You will find details 
of mapping Tk to Tkinter, along with a brief introduction to the widgets and their appearance. 

Chapter 3 illustrates application development with Tkinter using two calculator examples. The 
first is a simple no-frills calculator that demonstrates basic principles. The second is a partially finished 
application that shows you how powerful applications may be developed using Python’s and Tkinter’s 
capabilities. 











1.1 


Cc HAPTER 1 











Python 


1.1 Introduction to Python programming and a feature review 3 
1.2 Key data types: lists, tuples and dictionaries 5 
1.3 Classes 9 


This chapter defines the key features of Python that make the language ideal for rapid proto- 
typing of systems and for fully-functional applications. Python and Tkinter Programming is 
not intended to be a learning resource for beginning Python programmers; several other 
publications are better-suited to this task: Quick Python, Learning Python, Programming 
Python, Internet Programming in Python and The Python Pocket Reference are all excellent 
texts. Further information is provided in the “References” section at the end of this book. In 
this chapter, the key features of Python will be highlighted in concise examples of code to 
illustrate some of the building blocks that will be used in examples throughout the book. 


Introduction to Python programming and 
a feature review 


As stated earlier, this book is not intended to be used to learn Python basics directly. Pro- 
grammers experienced in other languages will be able to analyze the examples and discover 
the key points to programming in Python. However, if you are relatively new to program- 
ming generally, then learning Python this way will be a tough, upward struggle. 











1.1.1 


This chapter is really not necessary for most readers, then, since the material will already 
be familiar. Its purpose is to provide a refresher course for readers who worked with Python 
in the early days and a map for Tcl/Tk programmers and those readers experienced with other 
languages. 

Readers unfamiliar with object-oriented programming (OOP) may find section 1.3 use- 
ful as an introduction to OOP as it is implemented in Python. C++ or Java programmers who 
need to see how Python’s classes operate will benefit as well. 

Tm not going to explain the reasons why Python was developed or when, since this infor- 
mation is covered in every other Python book very well. I will state that Guido van Rossum, 
Python’s creator, has been behind the language since he invented it at Stichting Mathematisch 
Centrum (CWI) in Amsterdam, The Nederlands, around 1990; he is now at the Corporation 
for National Research Initiatives (CNRI), Reston, Virginia, USA. The fact that one person has 
taken control of the growth of the language has had a great deal to do with its stability and 
elegance, although Guido will be the first to thank all of the people who have contributed, in 
one way or another, to the language’s development. 

Perhaps more important than any of the above information is the name of the language. 
This language has nothing to do with snakes. Python is named after Monty Python’s Flying Cir- 
cus, the BBC comedy series which was produced from 1969 to 1974. Like many university stu- 
dents around 1970, I was influenced by Monty Python, so when I started writing this book I 
could not resist the temptation to add bits of Python other than the language. Now, all of you 
that skipped the boring beginning bit of this book, or decided that you didn’t need to read this 
paragraph are in for a surprise. Scattered through the examples you'll find bits of Python. If 
you have never experienced Monty Python, then I can only offer the following advice: if some- 
thing about the example looks weird, it’s probably Python. As my Yugoslavian college friend 
used to say “You find that funny”? 


Why Python? 


Several key features make Python an ideal language for a wide range of applications. Adding 
Tkinter to the mix widens the possibilities dramatically. Here are some of the highlights that 
make Python what it is: 


e Automatic compile to bytecode 
e High-level data types and operations 


Portability across architectures 

e Wide (huge) range of supported extensions 

e Object-oriented model 

e Ideal prototyping system 

e Readable code with a distinct C-like quality supports maintenance 
e Fasy to extend in C and C++ and embed in applications 


Large library of contributed applications and tools 


Excellent documentation 


You might notice that I did not mention an interpreter explicitly. One feature of Python 
is that it is a bytecode engine written in C. The extension modules are written in C. With a 
little care in the way you design your code, most of your code will run using compiled C since 
many operations are built into the system. The remaining code will run in the bytecode engine. 


CHAPTER 1 PYTHON 











1.1.2 


1.2 


1.2.1 


The result is a system that may be used as a scripting language to develop anything from some 
system administration scripts all the way to a complex GUI-based application (using database, 
client/server, CORBA or other techniques). 


Where can Python be used? 


Knowing where Python can be used is best understood by learning where it might vot be the 
best choice. Regardless of what I just said about the bytecode engine, Python has an interpre- 
tive nature, so if you can't keep within the C-extensions, there has to be a performance pen- 
alty. Therefore, real-time applications for high-speed events would be a poor match. A set of 
extensions to Python have been developed specifically for numerical programming (see 
“NumPy” on page 626). These extensions help support compute-bound applications, but 
Python is not the best choice for huge computation-intensive applications unless time isnt a 
factor. Similarly, graphics-intensive applications which involve real-time observation are not a 
good match (but see “Speed drawing” on page 271 for an example of what can be done). 


Key data types: lists, tuples and dictionaries 


Three key data types give Python the power to produce effective applications: two sequence 
classes—lists and tuples—and a mapping class—dictionaries. When they are used together, 
they can deliver surprising power in a few lines of code. 

Lists and tuples have a lot in common. The major difference is that the elements of a list 
can be modified in place but a tuple is immutable: you have to deconstruct and then reconstruct 
a tuple to change individual elements. There are several good reasons why we should care about 
this distinction; if you want to use a tuple as the key to a dictionary, it’s good to know that it 
can’t be changed arbitrarily. A small advantage of tuples is that they are a slightly cheaper 
resource since they do not carry the additional operations of a list. 

If you want an in-depth view of these data types take a look at chapters 6 and 8 of Quick Python. 


Lists 


Let’s look at lists first. If you are new to Python, remember to look at the tutorial that is avail- 
able in the standard documentation, which is available at www.python.org. 


Initializing lists 


Lists are easy to create and use. To initialize a list: 





lst = [] # Empty list 

ist => \["at;“b" 7. he") # String list 
lst = [1, 2, 3, 4] # Integer list 
Ist = [[1,2,3], ['a','b','c']] # List of lists 
Ist = [(1,'a'),(2,'b'), (3,'c')] # List of tuples 


Appending to lists 
Lists have an append method built in: 


lst.append('e') 
lst.append((5,'e')) 
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Concatenating lists 


Combining lists works well: 


lst = [1, 2, 3] + [4, 5, 6] 
print lst 
[1, 2, 3, 4, 5, 6] 


lterating through members 


Iterating through a list is easy: 


lst = ['first', 'second', 'third'] 
for str in lst: 
print 'this entry is %s' % str 
set = [(1, 'uno'), (2, 'due'), (3, 'tres')] 


str in set: 
n $a" 


for integer, 
print 'Numero 


in Italiano: é "%s"' % (integer, 


Sorting and reversing 

Lists have built-in sort and reverse methods: 
ist = [4, 5, 1, 9, 2] 
ilst.sort () 


print lst 
[Lg 24a By 291 


ist.reverse() 


print lst 
(9, 5, 4, 2, 1] 
Indexing 


Finding an entry in a list: 


lst = [1, 2, 4, 5, 9] 
print lst.index(5) 
3 

Member 


Checking membership of a list is convenient: 


if 'jeg' in ['abc', 'tuv', ‘'kie', 'jeg']: 


LE eS. in 1-23 *abe 
Modifying members 
A list member may be modified in place: 


et = Ply 2 th Sy 4 
ist[3] = 10 

print lst 

[1, 2, 4, 10, 9] 
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Inserting and deleting members 


To insert a member in a list: 


sts [1-2 Bi ay LO 9] 
lst.insert (4, 5) 

print lst 

[1, 2, 3, 4, 5, 10, 9] 


To delete a member: 


Pet. = (2, 27-85-43) ~ 107-94 
del 1st (4) 

print lst 

[1, 2, 3, 4, 9] 


Tuples 


Tuples are similar to lists but they are immutable (meaning they cannot be modified). Tuples 
are a convenient way of collecting data that may be passed as a single entity or stored in a list 
or dictionary; the entity is then unpacked when needed. 


Initializing tuples 
With the exception of a tuple containing ove element, tuples are initialized in a similar man- 
ner to lists (lists and tuples are really related sequence types and are readily interchangeable). 





tpl = () # Empty tuple 
tpl = (1,) # Singleton tuple 
tpl = (‘a', 'b', 'c') # String tuple 
tpl = (1, 2, 3, 4) # Integer tuple 
tpl = ([1,2,3], ['a','b','c']) # Tuple of lists 
tpl = ((1,'a'),(2,'b'), (3,'c')) # Tuple of tuples 


Iterating through members 


for 4. im tpl: 


for i,a in ((1, 'a'), (2, 'b'), (3, 'e')): 


Modifying tuples 


(But you said tuples were immutable!) 


a= 1, 2, 3 

a a[0], a[1], 10, a[2] 
a 

(1, 2, 10, 3) 


Il 


Note that you are not modifying the original tuple but you are creating a new name bind- 
ing for a. 
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1.2.3 Dictionaries 


Dictionaries are arrays of data indexed by keys. I think that they give Python the edge in 
designing compact systems. If you use lists and tuples as data contained within 
dictionaries you have a powerful mix (not to say that mixing code objects, dictionaries and 
abstract objects isn’t powerfull). 


Initializing dictionaries 


Dictionaries may be initialized by providing key: value pairs: 


dict = {} # Empty dictionary 
dice € {tatii “ly. Pte ters Sh # String key 

diet = {12 tat; 2a Ip; -33 Tet} # Integer key 
diet.= {Ls [1/23]; 24 [4561F # List data 


Modifying dictionaries 
Dictionaries are readily modifiable: 
dict['a'] = 10 

dict[10] = 'Larch' 


Accessing dictionaries 


Recent versions of Python facilitate lookups where the key may not exist. First, the old way: 


if dict.has_key('a') 
value = dict['a'] 
else: 
value = None 


or: 
try? 
value = dict['a'] 
except KeyError: 
value = None 


This is the current method: 


value = dict.get('a', None) 


Iterating through entries 
Get the keys and then iterate through them: 


keys = dict.keys() 
for key in keys: 


Sorting dictionaries 


Dictionaries have arbitrary order so you must sort the keys if you want to access the keys in order: 


keys = dict.keys().sort() 
for key in keys: 
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1.3 Classes 


1.3.1 


1.3.2 


1.3.3 


CLASSES 


I’m including a short section on Python classes largely for C++ programmers who may need to 
learn some of the details of Python’s implementation and for Python programmers who have 
yet to discover OOP in Python. 


How do classes describe objects? 
A class provides the following object descriptions: 


¢ The attributes (data-members) of the object 
e The behavior of the object (methods) 


e Where behavior is inherited from other classes (superclasses) 


Having said all that, C++ programmers will probably be tuning out at this point—but 
hold on for a little longer. There are some valuable features of Python classes, some of which 
may come as a bit of a surprise for someone who is not fully up to speed with Python OOP. 

Most of the examples of applications in this book rely heavily on building class libraries 
to create a wide range of objects. The classes typically create instances with multiple formats 
(see LEDs and Switches in chapter 7). Before we start building these objects, let’s review the 
rules and features that apply to Python classes. 


Defining classes 


A Python class is a user-defined data type which is defined with a class statement: 


class AClass: 
statements 


Statements are any valid Python statements defining attributes and member functions. In 
fact, any Python statement can be used, including a pass statement, as we will see in the next 
section. Calling the class as a function creates an instance of the class: 


anInstanceOfAClass = AClass() 


Neat Python trick #10 


A class instance can be used like a C structure or Pascal record. However, unlike C and Pascal, 
the members of the structure do not need to be declared before they are used—they can be 
created dynamically. We can use this ability to access arbitrary data objects across modules; 
examples using class instances to support global data will be shown later. 


class DummyClass: 
pass 


Colors = DummyClass() 


Colors.alarm = 'red' 
Colors.warning = '‘orange' 
Colors.normal = 'green' 


If the preceding lines are stored in a file called programdata.py, the following is a possible 
code sequence. 
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from programdata import Colors 


Button(parent, bg=Colors.alarm, text='Pressure\nVessel', 
command=evacuateBuilding) 


Alternately, if you apply a little knowledge about how Python manages data internally, 
you can use the following construction. 


class Record: 
def __init (self, **kw): 
self._ dict__.update (kw) 
Colors = Record(alarm='red', warning='orange', normal='green' ) 


Initializing an instance 


Fields (instance variables) of an instance may be initialized by including an __init__ 
method in the class body. This method is executed automatically when a new instance of the 
class is created. Python passes the instance as the first argument. It is a convention to name it 
self (it’s called this in C++). In addition, methods may be called to complete initialization. 
The __init__ methods of inherited classes may also be called, when necessary. 


class ASX200 (Frame) : 
def __init__(self, master=None) : 
Frame.__init__(self, master) 
Pack.config(self) 
self.state = NORMAL 
self.set_hardware_data(FOR 
self.createWidgets() 





Gl 


switch = ASX200() 





te To use instance variables you must reference the containing object (in the previ- 
Ne ous example it is switch. state, not self.state). If you make a reference to 
a variable by itself, it is to a local variable within the executing function, not an instance 
variable. 





Methods 


We have already encountered the __init__ method that is invoked when an instance is cre- 
ated. Other methods are defined similarly with def statements. Methods may take argu- 
ments: self is always the first or only argument. 

You will see plenty of examples of methods, so little discussion is really necessary. Note 
that Python accepts named arguments, in addition to positional arguments, in both methods 
and function calls. This can make supplying default values for methods very easy, since omis- 
sion of an argument will result in the default value being supplied. Take care when mixing posi- 
tional and named arguments as it is very easy to introduce problems in class libraries this way. 
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1.3.6 


1.3.7 


1.3.8 


1.3.9 


CLASSES 


Private and public variables and methods 


Unless you take special action, all variables and methods are public and virtual. If you make 
use of name mangling, however, you can emulate private variables and methods. You mangle 
the name this way: Any name which begins with a double-underscore (__) is private and is 
not exported to a containing environment. Any name which begins with a single underscore 
(_) indicates private by convention, which is similar to protected in C++ or Java. In fact, Python 
usually is more intuitive than C++ or other languages, since it is immediately obvious if a ref- 
erence is being made to a private variable or method. 


Inheritance 
The rules of inheritance in Python are really quite simple: 


e Classes inherit behavior from the classes specified in their header and from any classes 
above these classes. 

e Instances inherit behavior from the class from which they are created and from all the 
classes above this class. 


When Python searches for a reference it searches in the immediate namespace (the 
instance) and then in each of the higher namespaces. The first occurrence of the reference is 
used; this means that a class can easily redefine attributes and methods of its superclasses. If 
the reference cannot be found Python reports an error. 

Note that inherited methods are not automatically called. To initialize the base class, a 
subclass must call the __init__ method explicitly. 


Multiple inheritance 


Multiple inheritance in Python is just an extension of inheritance. If more than one class is 
specified in a class’s header then we have multiple inheritance. Unlike C++, however, Python 
does not report errors if attributes of classes are multiple defined; the basic rule is that the first 
occurrence found is the one that is used. 


Mixin classes 


A class that collects a number of common methods and can be freely inherited by subclasses is 
usually referred to as a mixin class (some standard texts may use base, generalized or abstract 
classes, but that may not be totally correct). Such methods could be contained in a Python 
module, but the advantage of employing a mixin class is that the methods have access to the 
instance self and thus can modify the behavior of an instance. We will see examples of mixin 
classes throughout this book. 
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Tkinter 


2.1 The Tkinter module 12 2.4 Tkinter class hierarchy 16 
2.2 Mapping Tcl/Tk to Tkinter 14 2.5 Tkinter widget appearance 17 
2.3 Win32 and Unix GUIs 15 


This chapter describes the structure of the Tkinter module and its relationship to Tcl/Tk. 
The mapping with Tcl/Tk constructs to Tkinter is explained in order to assist Tcl/Tk pro- 
grammers in converting to Tkinter from Tcl/Tk. Native GUIs for UNIX, Win32 and Mac- 
intosh implementations will be discussed and key architectural differences will be 
highlighted. Font and color selection will be introduced, and I'll cover this topic in more 
detail in “Tkinter widgets” on page 31. For readers who are unfamiliar with Tkinter, this 
chapter illustrates its importance to Python applications. 


The Tkinter module 


What is Tkinter? 


Tkinter provides Python applications with an easy-to-program user interface. Tkinter sup- 
ports a collection of Tk widgets that support most application needs. Tkinter is the Python 
interface to Tk, the GUI toolkit for Tcl/Tk. Tcl/Tk is the scripting and graphics facility 
developed by John Ousterhout, who was originally at University of California at Berkeley 
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2.1.2 


2.1.3 


and later at Sun Microsystems. Currently, Tcl/Tk is developed and supported by the Scriptics 
Corporation, which Ousterhout founded. Tcl/Tk enjoys a significant following with develop- 
ers in a number of fields, predominantly on UNIX systems, but more recently on Win32 sys- 
tems and MacOS. Ousterhout’s Tcl and the Tk Toolkit, which was the first Tcl/Tk book, is 
still a viable, though old, reference document for Tcl/Tk. (You will find some excellent newer 
texts on the subject in the section “References” on page 625 ). 

Tcl/Tk was first designed to run under the X Window system and its widgets and win- 
dows were made to resemble Motif widgets. The behavior of bindings and controls was also 
designed to mimic Motif. In recent versions of Tcl/Tk (specifically, release 8.0 and after), the 
widgets resemble native widgets on the implemented architecture. In fact, many of the widgets 
are native widgets and the trend to add more of them will probably continue. 

Like Python extensions, Tcl/Tk is implemented as a C library package with modules to 
support interpreted scripts, or applications. The Tkinter interface is implemented as a Python 
module, Tkinter.py, which is bound to a C-extension (_tkinter) which utilizes these same 
Tcl/Tk libraries. In many cases a Tkinter programmer need not be concerned with the imple- 
mentation of Tcl/Tk since Tkinter can be viewed as a simple extension of Python. 


What about performance? 


At first glance, it is reasonable to assume that Tkinter is not going to perform well. After all, 
the Python interpreter is utilizing the Tkinter module which, in turn, relies on the _tkinter 
interface which calls Tcl and Tk libraries and sometimes calls the Tcl interpreter to bind 
properties to widgets. Well, this is all true, but on modern systems it really does not matter 
too much. If you follow the guidelines in “Programming for performance” on page 348, you 
will find that Python and Tkinter have the ability to deliver viable applications. If your reason 
for using Python/Tkinter is to develop prototypes for applications, then the point is some- 
what moot; you will develop prototypes quickly in Python/Tkinter. 


How do I use Tkinter? 


Tkinter comprises a number of components. _tkinter, as mentioned before, is the low level 
interface to the Tk libraries and is linked into Python. Until recently, it was the programmer's 
responsibility to add Tkinter to the Python build, but beginning with release 1.5.2 of Python, 
Tkinter, Tcl and Tk are part of the installation package—at least for the Win32 distribution. 
For several UNIX variants and Macintosh, it is still necessary to build Python to include 
Tkinter. However, check to see if a binary version is available for your particular platform. 

Once a version of Python has been built and _tkinter has been included, as a shared 
library, dll or statically linked, the Tkinter module needs to be imported. This imports any 
other necessary modules, such as Tkconstants. 


tk ME 


To create a Tkinter window, type three lines into the Python com- 
mand line (or enter them into a file and type “python filename.py”). 


Figure 2.1 Trivial 
Example 
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from Tkinter import Label, mainloop 
Label (text=’This has to be the\nsimplest bit of code’) .pack() 
mainloop() 





Code comments 


First, we import components from the Tkinter module. By using from module import 
Label, mainloop we avoid having to reference the module to access attributes and methods 
contained in the module. 


We create a Label containing two lines of text and use the Pack geometry manager to realize 
the widget. 


Finally, we call the Tkinter mainloop to process events and keep the display activated. This 
example does not react to any application-specific events, but we still need a mainloop for it 
to be displayed; basic window management is automatic. 


What you will see is shown in figure 2.1. Now, it really cannot get much simpler than 
that! 


Tkinter features 


Tkinter adds object-oriented interfaces to Tk. Tcl/Tk is a command-oriented scripting lan- 
guage so the normal method of driving Tk widgets is to apply an operation to a widget identi- 
fier. In Tkinter, the widget references are objects and we drive the widgets by using object 
methods and their attributes. As a result, Tkinter programs are easy to read and understand, 
especially for C++ or Java programmers (although that is entirely another story!). 

One important feature that Tk gives to any Tkinter application is that, with a little care 
in selecting fonts and other architecture-dependent features, it will run on numerous flavors 
of UNIX, Win32 and Macintosh without modification. Naturally, there are some intrinsic dif- 
ferences between these architectures, but Tkinter does a fine job of providing an architecture- 
independent graphics platform for applications. 

It is the object-oriented features, however, that really distinguish Tkinter as an ideal plat- 
form for developing application frameworks. You will see many examples in this book where 
relatively little code will support powerful applications. 


Mapping Tcl/Tk to Tkinter 


Mapping of Tcl/Tk commands and arguments to Tkinter is really quite a simple process. 

After writing Tkinter code for a short time, it should be easy for a Tcl/Tk programmer to 

make the shift—maybe he will never go back to Tcl/Tk! Lers look at some examples. 
Commands in Tk map directly to class constructors in Tkinter. 





Txl/Tk Tkinter 





label .myLabel myLabel = Label(master) 
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Parent widgets (usually referred to as master widgets) are explicit in Tkinter: 





Tcl/Tk Tkinter 





label .screen.for label = Label{form) (screen is form's parent) 





For configuration options, Tk uses keyword arguments followed by values or configure 
commands; Tkinter uses either keyword arguments or a dictionary reference to the option of 
the configure method in the target widget. 








Tcl/Tk Tkinter 
label .myLabel -bg blue myLabel = Label(master, bg="blue") 
.myLabel configure -bg blue myLabel[”“bg"] = ”blue” 


myLabel.configure(bg = “blue”) 





Since the Tkinter widget object has methods, you invoke them directly, adding argu- 
ments as appropriate. 





Tel/Tk Tkinter 
pack label -side left -fill y label.pack(side=LEFT, fill=Y) 








The following illustration demonstrates how we access an inherited method pack from the 
Packer. This style of programming contributes to the compact nature of Tkinter applications 
and their ease of maintenance and reuse. 


Full mappings of Tk to Tkinter are provided in “Mapping Tk to Tkinter” on page 383. 


Win32 and Unix GUIs 


As I mentioned earlier, it is reasonable to develop Tkinter applications for use in Win32, 
UNIX and Macintosh environments. Tcl/Tk is portable and can be built on the specific plat- 
form, as can Python, with its _tkinter C module. Using pmw* (Python MegaWidgets), 
which provides a portable set of composite widgets and is 100% Python code, it is possible to 
use the bytecode generated on a UNIX system on a Win32 or Macintosh system. What you 
cannot control is the use of fonts and, to a lesser extent, the color schemes imposed by the 
operating system. 





* Pmw—Python MegaWidgets provide complex widgets, constructed from fundamental Tkinter wid- 
gets, which extend the available widgets to comboboxes, scrolled frames and button boxes, to name a 
few. Using these widgets gives GUI developers a rich palette of available input devices to use in their 
designs. 
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Set Thresholds 


BER [1xi06 |¥| [Alarm Over _¥| 
VswR [1:2 _¥| Alarm Over | ¥| 
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Reset 
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Figure 2.2 Tkinter and Pmw on win32 
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Figure 2.3 Tkinter and Pmw running on UNIX 


2.4 Tkinter class hierarchy 





Take a look at figure 2.2. This 
application uses Pmw combobox widgets 
along with Tkinter button and entry 
widgets arranged within frames. The 
font for this example is Arial, bold and 
16 point. Apart from the obvious Win32 
controls in the border, there is little to 
distinguish this window from the one 
shown in figure 2.3, which was run on 
UNIX. In this case, the font is Helvetica, 
bold and 16 point. The window is 
slightly larger because the font has 
slightly different kerning rules and stroke 
weight, and since the size of the widget is 
dependent on the font, this results in a 
slightly different layout. If precise align- 
ment and sizing is an absolute require- 
ment, it is possible to detect the platform 
on which the application is running and 
make adjustments for known differ- 
ences. In general, it is better to design an 
application that is not sensitive to small 
changes in layout. 

If you look closely, you may also 
notice a difference in the top and bottom 
highlights for the Execute and Close but- 
tons, but not for the buttons on the Pmw 
widgets. This is because Tk is drawing 
Motif decorations for UNIX and Win- 
dows SDK decorations for Win32. 

In general, as long as your applica- 
tion does not make use of very platform- 
specific fonts, it will be possible to 
develop transportable code. 


Unlike many windowing systems, the Tkinter hierarchy is really quite simple; in fact, there 


really isnt a hierarchy at all. The WM, Misc, Pack, Place and Grid classes are mixins to each 


of the widget classes. Most programmers only need to know about the lowest level in the tree 
to perform everyday operations and it is often possible to ignore the higher levels. The 


notional “hierarchy” is shown in figure 2.4. 
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Figure 2.4 Tkinter widget “hierarchy” 


File Object Edit View Tools Help 





Button |  CheckButton C Ra © Dio C Button 
| Label widget: Entry widget 1 




















In Dutch, the "G" in Guido is a hard G, pronounced roughly like the "ch" in 
Scottish "loch". (Listen to the sound clip below.) However, if you're American, 
‘you may also pronounce it as the Italian "Guido". I'm not too worried about the 
associations with mob assassins that some people have :-) 





Spelling: 

My last name is two words, and I'd like keep it that way, the spelling on my 

credit card notwithstanding. Dutch spelling rules dictate that when used 

in combination with my first name, "van" is not capitalized: "Guido van 

Rossum". But when my lastname is used alone to refer to me, it is xj 
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This is a Message widget 


Figure 2.5 Tkinter widgets: a collage 
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2.5 Tkinter 
widget 
appearance 


To conclude this initial introduction 
to Tkinter, lets take a quick look at 
the appearance of the widgets avail- 
able to a programmer. In this exam- 
ple, we are just looking at the basic 
configuration of the widgets and only 
one canvas drawing option is shown. 
Tve changed the border on the frames 
to add some variety, but you are see- 
ing the widgets with their default 
appearance. The widgets are shown in 
figure 2.5. The code is not presented 
here, but it is available online. 


17 











CHAPTER 3 











Building an application 


3.1 Calculator example: key features 21 

3.2. Calculator example: source code 21 

3.3. Examining the application structure 27 
3.4 Extending the application 28 


Most books on programming languages have followed Kernigan and Ritchie’s example and 
have presented the obligatory “Hello World” example to illustrate the ease with which that 
language may be applied. Books with a GUI component seem to continue this tradition 
and present a “Hello GUI World” or something similar. Indeed, the three-line example 
presented on page 13 is in that class of examples. 


SAE There is a growing trend to present a calculator example in 
EEA recent publications. In this book I am going to start by present- 
ing a simple calculator (you may add the word obligatory, if you 
wish) in the style of its predecessors. The example has been writ- 
ten to illustrate several Python and Tkinter features and to dem- 
onstrate the compact nature of Python code. 

The example is not complete because it accepts only 
mouse input; in a full example, we would expect keyboard input 





as well. However, it does work and it demonstrates that you do 
not need a lot of code to get a Tkinter screen up and running. 


Figure 3.1 A simple : 
calculator Let’s take a look at the code that supports the screen: 
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calc1.py 


from Tkinter import * 


def frame(root, side): 





w = Frame(root) 
w.pack(side=side, expand=YES, fi11=BOTH) 
return w 
def button(root, side, text, command=None) : 
w = Button(root, text=text, command=command) 
w.pack(side=side, expand=YES, fi11=BOTH) 
return w 
class Calculator (Frame): 
def __init__(self): 
Frame.__init__ (self) 
self.pack(expand=YES, £i11=BOTH) #9 
self.master.title('Simple Calculator') 
self.master.iconname("calc1") 


display = StringVar() 
Entry(self, relief=SUNK 











EN , 
textvariable=display) .pack(side=TOP, 


expand=YES, 











£i11=BOTH) 
for key in ("123", "456", "789", "-0."): 
keyF = frame(self, TOP) 
for char in key: 
button(keyF, LEFT, char, 
lambda w=display, s=' %s '%Schar: w.set(w.get()+s) ) © 
opsF = frame (self, TOP) 
for char in "+-*/=": 
if char =5 Sty 
btn = button(opsF, LEFT, char) 
btn. bind('<ButtonRelease-1>', 
lambda e, s=self, w=display: s.calc(w), '+') | 
else: 
btn = button(opsF, LEFT, char, 
lambda w=display, c=char: w.set(w.get()+' '+c+' ')) 
clearF = frame(self, BOTTOM) 
button(clearF, LEFT, 'Clr', lambda w=display: w.set('')) 


def calc(self, 
try: 


display): 


display.set (‘eval (display.get())~) 





except ValueError: 


display.set ("ERROR" 





Te == 


__name__ '_ main__': 
Calculator ().mainloop() 


0 


) 
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Code comments 


We begin by defining convenience functions to make the creation of frame and button wid- 
gets more compact. These functions use the pack geometry manager and use generally useful 
values for widget behavior. It is always a good idea to collect common code in compact func- 
tions (or classes, as appropriate) since this makes readability and maintenance much easier. 


We call the Frame constructor to create the toplevel shell and an enclosing frame. Then, we 
set titles for the window and icon. 


Next, we create the display at the top of the calculator and define a Tkinter variable which 
provides access to the widget’s contents: 
display = StringVar() 
Entry(self.master, relief=SUNKEN, 
textvariable=variable) .pack(side=TOP, expand=YES, 
£i11=BOTH) 








Remember that character strings are sequences of characters in Python, so that each of the 
subsequences is really an array of characters over which we can iterate: 
for key in ("123", "456", "789", "-0."): 
keyF = frame(self, TOP) 
for char in key: 


We create a frame for each row of keys. 
We use the convenience function to create a button, passing the frame, pack option, label 
and callback: 
button(keyF, LEFT, char, 
lambda w=display, c=char: w.set(w.get() + c)) 
Don't worry about the Lambda form of the callback yet, I will cover this in more detail 
later. Its purpose is to define an inline function definition. 
The = key has an alternate binding to the other buttons since it calls the calc method when 
the left mouse button is released: 
btn. bind('<ButtonRelease-1>', 
lambda e, s=self, w=display: s.calc(w) ) 


The calc method attempts to evaluate the string contained in the display and then it replaces 





the contents with the calculated value or an ERROR message: 
display.set (*eval(display.get())°*) 


Personally, I don’t like the calculator, even though it demonstrates compact code and will 
be quite easy to extend to provide more complete functionality. Perhaps it is the artist in me, 
but it doesn’t look like a calculator! 

Let’s take a look at a partly-finished example application which implements a quite 
sophisticated calculator. It has been left unfinished so that curious readers can experiment by 
adding functionality to the example (by the time you have finished reading this book, you will 
be ready to build a Cray Calculator!). Even though the calculator is unfinished, it can still be 
put to some use. As we will discover a little later, some surprising features are hidden in the 
reasonably short source code. 

Let’s start by taking a look at some of the key features of the calculator. 
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3.1 Calculator example: key features 


The calculator example illustrates many features of applications written in Python and 
Tkinter, including these: 


© GUI application structure Although this is a simple 
example, it contains many of the elements of larger 

applications that will be presented later in the book. 
62.7517335 e Multiple inheritance Tt is simple in this example, but it 
illustrates how it may be used to simplify Python code. 
It ascent crs e Lists, dictionaries and tuples As mentioned in 
chapter 1, these language facilities give Python a con- 
siderable edge in building concise code. In particular, 
; | this example illustrates the use of a dictionary to dis- 

ael Mode Del a Eeg h . h d Of 7 i | on i h 

patch actions to methods. Of particular note is the use 
of lists of tuples to define the content of each of the 
keys. Unpacking this data generates each of the keys, 


GI c 


Mtrx Prgm | LELES | Cir 


e a (a 


m | rs labels and associated bindings in a compact fashion. 

° Pmw (Python megawidgets) The scrolled text widget is 
implemented with Pmw. This example illustrates set- 
ting its attributes and gaining access to its components. 

e Basic Tkinter operations Creating widgets, setting 
attributes, using text tags, binding events and using a 
geometry manager are demonstrated. 

* eval and exec functions The example uses eval to 
perform many of the math functions in this example. 
However, as you will see later in this chapter, eval can- 
not be used to execute arbitrary Python code; exec is 
used to execute single or multiple lines of code (and 





Figure 3.2 multiple lines of code can include control flow 
A better calculator structures). 


3.2 Calculator example: source code 


calc2.py 


from Tkinter import * 


import Pmw @ Python MegaWidgets 


class SLabel (Frame) : 
""" Stabel defines a 2-sided label within a Frame. The 
left hand label has blue letters; the right has white letters. """ 
def _ init__(self, master, leftl, rightl): 
Frame.__init__ (self, master, bg='gray40') 
self.pack(side=LEFT, expand=YES, f£i11=BOTH) 
Label(self, text=leftl, fg='steelbluel', 
font=("arial", 6, "bold"), width=5, bg='gray40') .pack ( 
side=LEFT, expand=YES, fi11=BOTH) 
Label(self, text=rightl, fg='white', 
font=("arial", 6, "bold"), width=1, bg='gray40') .pack( 
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side=RIGHT, expand=YES, fil1=BOTH) 


class Key (Button): 
def _ init_ (self, master, font=('arial', 8, 'bold'), 
fg='white',width=5, borderwidth=5, **kw): 


kw['font'] = font 

kw['fg'] = fg 

kw['width'] = width 
kw['borderwidth'] = borderwidth 





apply(Button.__init__, (self, master), kw) 
self.pack(side=LEFT, expand=NO, fill=NONE 





class Calculator (Frame): 
def _ init_ (self, parent=None): 

Frame.__ init__(self, bg='gray40') 
self.pack(expand=YES, fi11=BOTH) 
self.master.title('Tkinter Toolkit TT-42') 
self.master.iconname('Tk-42') 
self.calc = Evaluator () # This is our evaluator 
self.buildCalculator () # Build the widgets 


# This is an incomplete dictionary - a good exercise! 
self.actionDict = {'second': self.doThis, 'mode': self.doThis, 














'delete': self.doThis, ‘alpha': self.doThis, 
'stat': self.doThis, 'math': self.doThis, 
'matrix': self.doThis, 'program': self.doThis, 
'vars': self.doThis, 'clear': self.clearall, 
rsin" self.doThis, 'cos': self.doThis, | 98 
'tan': self.doThis, ‘up': self.doThis, 
'X1': self.doThis, 'X2': self.doThis, 
log" self.doThis, 'ln': self.doThis, 
"store': self.doThis, 'off': self.turnoff 
'neg': self.doThis, '‘enter': self.doEnter, 
} 


self.current = "" 


def doThis(self,action): 
print '"%s" has not been implemented' % action 


def turnoff(self, *args): 
self.quit() 


def clearall(self, *args): 
self.current = "" 
self.display.component ('text').delete(1.0, END) (4) 





def doEnter (self, *args): 
self.display.insert (END, '\n') 


result = self.calc.runpython(self.current) O 
if result: 
self.display.insert (END, '%s\n' % result, 'ans') O 
self.current = "" 
def doKeypress (self, event): 
key = event.char 
if key != '\b': 
self.current = self.current + key 
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else: 
self.current = self.current[:-1] 


def keyAction(self, key): 
self.display.insert (END, key) 
self.current = self.current + key 





def evalAction(self, action): 
try: 
self.actionDict [action] (action) 
except KeyError: 
pass 








Code comments 
Pmw (Python MegaWidgets) widgets are used. These widgets will feature prominently in this 
book since they provide an excellent mechanism to support a wide range of GUI requirements 
and they are readily extended to support additional requirements. 
In the constructor for the Key class, we add key-value pairs to the kw (keyword) dictionary 
and then apply these values to the Button constructor. 
def _init__(self, master, font=('arial', 8, 'bold'), 
fg='white',width=5, borderwidth=5, **kw): 
kw['font'] = font 
apply(Button. init, (self, master), kw) 
This allows us a great deal of flexibility in constructing our widgets. 


The Calculator class uses a dictionary to provide a dispatcher for methods within the class. 





'matrix': self.doThis, 'program': self.doThis, 
'vars': self.doThis, 'clear': self.clearall, 
'sin': self.doThis, 'cos': self.doThis, 


Remember that dictionaries can handle much more complex references than the rela- 
tively simple cases we need for this calculator. 


We use a Pmw ScrolledText widget, which is a composite widget. To gain access to the 
contained widgets, the component method is used. 
self.display.component ('text').delete(1.0, END) 
When the ENTER key is clicked, the collected string is directed to the calculator’s evaluator: 
result = self.calc.runpython(self.current) 
The result of this evaluation is displayed in the scrolled text widget. 


The final argument in the text insert function is a text tag 'ans' which is used to change the 
foreground color of the displayed text. 





self.display.insert (END, '%s\n' % result, 'ans') 
doKeypress is a callback bound to all keys. The event argument in the callback provides the 
client data for the callback. event .char is the key entered; several attributes are available in 
the client data, such as x-y coordinates of a button press or the state of a mouse operation (see 
“Tkinter events” on page 98). In this case we get the character entered. 


A simple exception mechanism to take action on selected keys is used. 
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calc2.py (continued) 


def buildCalculator(self): 


FUN 
KEY 
KCL 
KC2 
KC3 
KC4 
keys 


self.display = 
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T 
= 0 
= 'gray30' 
= 'gray50' 
= 'steelbluel' 
= 'steelblue' 
= I 
[('2nd', Te TAg 
('Mode', 'Quit', 
('Del', INS! 
('Alpha', 'Lock', 
("Stat', 'List', 
[('Math', 'Test', 
('Mtrx', 'Angle' 
('Prgm', 'Draw', 
('Vars', 'YVars' 
CLr" E ee 
[('X- 1", 'Abs' 
('Sin', 'Sin-1', 
('Cos', 'Cos-1', 
('Tan', ‘'Tan-1', 
Gary. SBE a HH 
[('X2', "Root', ' 
a ‘EE', 'J', 
CO, CE CKS, 
Oa A TE 
Gp Pg, My 
[('Log', LORS 
CUE 'Un-1', 
CEB 'vn-1', 
pory Pis Os 
ORe De VRE 
[('Ln', ‘ex', 
CM, 'L4', rin, 
(Sk usa 
De "GT, patie 
8 i Prensa 
[('s70', 'RCL', 
CSLI ‘LEY, ks 
Cra, ts Cae 
(uss; U3", us 
(‘+', 'MEM', '" 
DOER “re: "ee 
ye ais pay 
C+)", TANS", 
('Enter','Entry',' 


'O', 
'P', 


‘St, 


Pmw.ScrolledText (self, 
vscrollmode='dynamic' 
hull_background='gray40', 












































# A Function 
# A Key © 
# Dark Keys 
# Light Keys 
# Light Blue Key 
# Dark Blue Key 
KC3, FUN, 'second'), # Row 1 
Maia KC1, FUN, 'mode'), 
'!, KC1, FUN, 'delete'), 
es KC2, FUN, '‘alpha'), 
'') KC1, FUN, 'stat')], 
vA! KC1, FUN, 'math'), # Row 2 
. BY KC1, FUN, 'matrix'), 
“Ge KC1, FUN, 'program'), 
hs KC1, FUN, ‘'vars'), 
KC1, FUN, ‘'clear')], 
YD? KC1, FUN, 'X1'), # Row 3 
“ES KC1, FUN, 'sin'), 
Et KC1, FUN, 'cos'), 
'G', KCl, FUN, ‘'tan'), 
KC1, FUN, ‘up')], 
I', KCl, FUN "BAS Pa # Row 4 
KCL, "KEY; TtT 
KC1, KEY, '('), 
KC1, KEY, ')'), 
KC4, KEY, '/')], 
'N', KCl, FUN, '‘log'), # Row 5 
KC2, KEY, '7'), 
KC2, KEY, '8'), 
KC2, KEY, '9'), 
KC4, KEY, '*')], 
KC1, FUN, ‘ln'), # Row 6 
KC2, KEY, '4') 
KC2, KEY, '5') 
KC2, KEY, '6'), 
KC4, KEY, '-')], 
'X', KCl, FUN, 'store'), # Row 7 
KO2y, REY ALS 
KC2, KEY, '2'), 
KC2, KEY, '3'), 
', KC4, KEY, '‘'+')], 
KC1, FUN, '‘off'), # Row 8 
KC2, KEY, '0'), 
KC2, KEY, '.'), 
'?', KC2, FUN, ‘'neg'), 
', KC4, FUN, ‘enter')]] 


hscrollmode='dynamic' © 
hull_relief='sunken' 
hull_borderwidth=10, 
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text_background='honeydew4', text_width=16, 
text_foreground='black', text_height=6, 
text_padx=10, text_pady=10, text_relief='groove', 
text_font=('arial', 12, 'bold')) 
self.display.pack(side=TOP, expand=YES, f£i11=BOTH) 


self.display.tag_config('ans', foreground='white') D 
self.display.component ('text').bind('<Key>', self.doKeypress) 
self.display.component ('text').bind('<Return>', self.doEnter) 


for row in keys: 
rowa = Frame(self, bg='gray40') 
rowb = Frame(self, bg='gray40') 
for pl, p2, p3, color, ktype, func in row: 
if ktype == FUN: 
a = lambda s=self, a=func: s.evalAction(a) 
else: 
a = lambda s=self, k=func: s.keyAction(k) 
SLabel (rowa, p2, p3) 
Key (rowb, text=p1, bg=color, command=a) 
rowa.pack(side=TOP, expand=YES, fill=BOTH) 
rowb.pack(side=TOP, expand=YES, fi11=BOTH) 








class Evaluator: 
def __init__(self): 
self.myNameSpace = {} 
self.runpython("from math import *") 


def runpython(self, code): 
try: 





return ‘eval(code, self.myNameSpace, self .myNameSpace) ~ (13, 
except SyntaxError: 
try: 
exec code in self.myNameSpace, self.myNameSpace D 
except: 





return 'Error' 


Calculator ().mainloop() 





Code comments (continued) 


© A number of constants are defined. The following data structure is quite complex. Using con- 
stants makes it easy to change values throughout such a complex structure and they make the 
code much more readable and consequently easier to maintain. 





FUN = 1 # A Function 
KEY = 0 # A Key 

KCl -= 'gray30' # Dark Keys 
KC2 = 'gray50' # Light Keys 


These are used to populate a nested list of lists, which contains tuples. The tuples store 
three labels, the key color, the function or key designator and the method to bind to the key’s 
cmd (activate) callback. 


@ We create the Pmw ScrolledText widget and provide values for many of its attributes. 


self.display = Pmw.ScrolledText (self, hscrollmode='dynamic', 
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vscrollmode='dynamic', hull_relief='sunken', 
hull_background='gray40', hull_borderwidth=10, 
text_background='honeydew4', text_width=16, 


Notice how the attributes for the hul1 (the container for the subordinate widgets within 


Pmw widgets) and the text widget are accessed by prefixing the widget. 


We define a text tag which is used to differentiate output from input in the calculator’s screen. 


self.display.tag_config('ans', foreground='white' ) 


We saw this tag in use earlier in the text insert method. 


Again, we must use a lambda expression to bind our callback function. 


Python exceptions are quite flexible and allow simple control of errors. In the calculator’s 


evaluator (runpython), we first run eval. 


try: 


return ‘eval(code, self.myNameSpace, self.myNameSpace) ~* 


This is used mainly to support direct calculator math. eval cannot handle code sequences, 
however, so when we attempt to eval a code sequence, a SyntaxError exception is raised. 


We trap the exception: 


except SyntaxError: 


try: 


exec code in self.myNameSpace, self.myNameSpace 


except: 


return 


'Error' 


and then the code is exec’ed in the except clause. Notice how this is enclosed by another 


try... except clause. 


Fae ol) 
_stderr__','__stdin_','_ 


_stdout__', ‘argv’, ‘builtin 
_module_names'’, ‘copyri 


[_doc_',' 





Figure 3.3 Python input 


atform'’, ‘prefix’, 'setcheck 
interval’, 'setprofile', 'settr 
ace', 'stderr', 'stdin', 'stdo 


ut', 'version', 'winver'] 





Figure 3.4 Output 
from dir() 


Figure 3.2 shows the results of clicking keys on the cal- 
culator to calculate simple math equations. Unlike many cal- 
culators, this displays the input and output in different 
colors. The display also scrolls to provide a history of calcu- 
lations, not unlike a printing calculator. If you click on the 
display screen, you may input data directly. Here is the sur- 
prise: you can enter Python and have exec run the code. 

Figure 3.3 shows how you can import the sys module 
and access built-in functions within Python. Technically, 
you could do almost anything from this window (within the 
constraint of a very small display window). However, I don’t 
think that this calculator is the much-sought Interactive 
Development Environment (IDE) for Python! (Readers who 
subscribe to the Python news group will understand that 
there has been a constant demand for an IDE for Python. 
Fortunately, Guido Van Rossum has now released IDLE 
with Python.) 

When you press ENTER after dir (), you will see output 


similar to figure 3.4. This list of built-in symbols has scrolled the display over several lines (the 


widget is only 16 characters wide, after all). 
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Because we are maintaining a local namespace, it is possible 
mT mee to set up an interactive Python session that can do some use- 
ful work. Figure 3.5 shows how we are able to set variables 
within the namespace and manipulate the data with built-ins. 





Figure 3.5 Variables and 
built-in functions 


Figure 3.6 is yet another example of our ability to gain access 
to the interpreter from an interactive shell. While the exam- 
ples have been restricted to operations that fit within the lim- 
ited space of the calculator’s display, they do illustrate a 
ree ee ya potential for more serious applications. Note how Python 
allows you to create and use variables within the current 





namespace. 


Figure 3.6 Using the math 
module 





Note When developing applications, I generally hide a button or bind a “secret” key 

sequence to invoke a GUI which allows me to execute arbitrary Python so that 
I can examine the namespace or modify objects within the running system. It is really a 
miniature debugger that I always have access to during development when something 
unusual happens. Sometimes restarting the application for a debug session just does not 
get me to the solution. An example of one of these tools is found in “A Tkinter explorer” 


on page 334. 





3.3 Examining the application structure 


The calculator example derives its compact code from the fact that Tkinter provides much of 
the structure for the application. Importing Tkinter establishes the base objects for the system 
and it only requires a little extra code to display a GUI. In fact, the minimal Tkinter code that 
can be written is just four lines: 

from Tkinter import * 

aWidget = Label(None, text=’How little code does it need?’) 

aWidget .pack () 

aWidget .mainloop() 


In this fragment, the label widget is realized with the pack method. A mainloop is nec- 
essary to start the Tkinter event loop. In our calculator example, the application structure is a 
little more complex: 


from Tkinter import * 
define helper classes 


class Calculator: 
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3.4 





create widgets 
Calculator.mainloop() 


Calling calculator.mainloop() creates a 
imported modules calculator instance and starts the mainloop. 

As we develop more applications, you will see 
this structure repeatedly. For those of us that tend 
to think spatially, the diagram shown in figure 3.7 
may help. 

All we have to do is fill in the blocks and we’re 
finished! Well, nearly finished. I believe that the 











‘global’ data 








Helper Classes 
and Functions 














Main Class most important block in the structure is the last 
one: “Test Code.” The purpose of this section is to 
GUI Init allow you to test a module that is part of a suite of 








modules without the whole application structure 


TUS aL being in place. Writing Python code this way will 














Test Code save a great deal of effort in integrating the com- 





ponents of the application. Of course, this 


Figure 3.7 Application structure approach applies to any implementation. 


Extending the application 


I leave you now with an exercise to extend the calculator and complete the functions that have 
been left undefined. It would be a simple task to modify the keys list to remove unnecessary 
keys and produce a rather more focused calculator. It would also be possible to modify the 
keys to provide a business or hex calculator. 

In subsequent examples, you will see more complex manifestations of the application 
structure illustrated by this example. 
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Displays 


I, this section of the book we are going to examine the components that are used to build an appli- 
cation. We will begin with Tkinter widgets in chapter 4 and an explanation of their key features and 
their relationship to the underlying Tk widgets they are driving. Remember that Tkinter provides an 
object-oriented approach to GUIs, so that even though the behavior of the widgets is the same as those 
widgets created within a Tcl/Tk program, the methods used to create and manipulate them are quite 
different from within a Tkinter program. 

Once we have looked at the widgets and examined Pmw (Python Mega Widgets), which provides 
a valuable library of application-ready widgets, we will discuss laying out the screen using the various 
geometry managers that are defined in chapter 5. 

Chapter 6 explains how to make your application react to external events. This is an important 
chapter, since it covers a variety of methods for handling user input. 

Chapter 7 shows the application of classes and inheritance as they apply to Tkinter. This is impor- 
tant for programmers new to object-oriented programming and it may be useful for those who are used 
to OOP as it applies to C++ and Java, since there are some notable differences. Then, in chapter 8, I 
will introduce more advanced techniques to drive a variety of dialogs and other interaction models. 

Chapter 9 introduces panels and machines; this may be a new idea to some readers. It shows how 
to construct innovative user interfaces which resemble (in most cases) the devices that they control or 
monitor. 

Chapter 10 gives information on building interfaces that permit the user to draw objects on a 
screen. It then explains methods to change their properties. You will also find some example code which 
illustrates how Tcl/Tk programs from the demonstration programs distributed with the software can 
be converted to Tkinter quite easily. Chapter 11 explains how to draw graphs using fairly conventional 
two-dimensional plots along with some alternative three-dimensional graphics. 
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Tkinter widgets 


4.1 Tkinter widget tour 31 

4.2 Fonts and colors 47 

4.3 Pmw Megawidget tour 49 
4.4 Creating new megawidgets 73 


In this chapter IIl present the widgets and facilities available to Tkinter. Pmw Python Mega- 
Widgets, will also be discussed, since they provide valuable extensions to Tkinter. Each 
Tkinter and Pmw widget will be shown along with the source code fragment that produces 
the display. The examples are short and simple, although some of them illustrate how easy it 
is to produce powerful graphics with minimal code. 

This chapter will not attempt to document all of the options available to a Tkinter pro- 
grammer; complete documentation for the options and methods available for each widget is 
presented in appendix B. Similarly, Pmw options and methods are documented in 
Appendix C. Uses these appendices to determine the full range of options for each widget. 


Tkinter widget tour 


The following widget displays show typical Tkinter widget appearance and usage. The code 
is kept quite short, and it illustrates just a few of the options available for the widgets. Some- 
times one or more of a widget’s methods will be used, but this only scratches the surface. If 


3I 
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you need to look up a particular method or option, refer to appendix B. Each widget also has 
references to the corresponding section in the appendix. 

With the exception of the first example, the code examples have been stripped of the boil- 
erplate code necessary to import and initialize Tkinter. The constant code is shown bolded in 
the first example. Note that most of the examples have been coded as functions, rather than 
classes. This helps to keep the volume of code low. The full source code for all of the displays 
is available online. 


Toplevel 
The Toplevel widget provides a separate container for other widgets, such as a Frame. For 


simple, single-window applications, the root Toplevel created when you initialize Tk may be 
the only shell that you need. There are four types of toplevels shown in figure 4.1: 


1 The main toplevel, which is normally referred to as the root. 


2 A child toplevel, which acts independently to the root, unless the root is destroyed, in 
which case the child is also destroyed. 


3 A transient toplevel, which is always drawn on top of its parent and is hidden if the par- 
ent is iconified or withdrawn. 

4 A Toplevel which is undecorated by the window manager can be created by setting the 
overrideredirect flag to a nonzero value. This creates a window that cannot be 
resized or moved directly. 


Toplevel 








No wm decorations 
This is a child of root 
Toplevel x] 


This is a transient window of root Figure 4.1 
Toplevel widgets 





from Tkinter import * 

root = Tk() 

root .option_readfile('optionDB' ) 
root.title('Toplevel') 


Label (root, text='This is the main (default) Toplevel') .pack(pady=10) 

tl = Toplevel (root) 

Label(t1, text='This is a child of root') .pack(padx=10, pady=10) 

t2 = Toplevel (root) 

Label (t2, text='This is a transient window of root').pack(padx=10, pady=10) 
t2.transient (root) 

t3 = Toplevel(root, borderwidth=5, bg='blue') 
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Label (t3, text='No wm decorations', bg='blue', fg='white').pack(padx=10, 


pady=10) 
t3.overrideredirect (1) 
t3.geometry ('200x70+150+150') 


root .mainloop() 





Note The use of the option_readfile call in each of the examples to set applica- 

tion-wide defaults for colors and fonts is explained in “Setting application-wide 
default fonts and colors” on page 49. This call is used to ensure that most examples have 
consistent fonts and predictable field sizes. 





Documentation for the Toplevel widget starts on page 539. 


Frame 


Frame widgets are containers for other widgets. Although you can bind mouse and keyboard 
events to callbacks, frames have limited options and no methods other than standard widget 
options. 

One of the most common uses for a frame is as a master for a group of widgets which will 
be handled by a geometry manager. This is shown in figure 4.2. The second frame example, 
shown in figure 4.3 below, uses one frame for each row of the display. 


Frames 





raised | | sunken ridge 


Figure 4.2 Frame widget 


for relief in [RAISED, SUNKEN, FLAT, RIDGE, GROOVE, SOLID]: 
f = Frame(root, borderwidth=2, relief=relief) 
Label(f, text=relief, width=10) .pack(side=LEFT) 
f.pack(side=LEFT, padx=5, pady=5) 








In a similar manner to buttons and labels, the appearance of the frame can be modified 
by choosing a relief type and applying an appropriate borderwidth. (See figure 4.3.) In fact, it 
can be hard to tell the difference between these widgets. For this reason, it may be a good idea 
to reserve particular decorations for single widgets and not allow the decoration for a label to 
be used for a button, for example: 


class GUI: 
def __init__(self): 

of = [None] *5 

for bdw in range(5): 
of[bdw] = Frame(self.root, borderwidth=0) 
Label (of[bdw], text='borderwidth = %d ' % bdw) .pack(side=LEFT) 
ifx = 0 
ife = [i 
for relief in [RAISED, SUNKEN, FLAT, RIDGE, GROOVE, SOLID]: 
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iff.append(Frame(of[bdw], borderwidth=bdw, relief=relief) ) 
Label (iff[ifx], text=relief, width=10) .pack(side=LEFT) 
iff[ifx] .pack(side=LEFT, padx=7-bdw, pady=5+bdw) 
ifx = ifx+1 

£ [bdw] . pack () 







borderwidth = 0 raised sunken flat ridge groove solid 
borderwidth = 1 raised sunken flat ridge groove 








borderwidth = 2 raised | | sunken flat 
borderwidth = 3 raised | J sunken flat | groove 


borderwidth = 4 raised | J sunken [ridge || groove | [soa 


Figure 4.3 Frame styles combining relief type with varying 
borderwidths 
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A common use of the GROOVE relief type is to provide a labelled frame (sometimes called 
a panel) around one or more widgets. There are several ways to do this; figure 4.4 illustrates 
just one example, using two frames. Note that the outer frame uses the Placer geometry man- 
ager to position the inner frame and label. The widgets inside the inner frame use the Packer 
geometry manager. 


IPLA du gE 





m Self-defence against fruit 
You shot him! 


He's dead! | He's completely dead! | 





Figure 4.4 Using a Frame 
widget to construct a panel 











f£ = Frame(root, width=300, height=110) 
xf = Frame(f, relief=GROOVE, borderwidth=2) 
Label (xf, text="You shot him!") .pack(pady=10) 








Button(xf, text="He's dead!", state=DISABLED) .pack(side=LEFT, padx=5, 
pady=8) 
Button(xf, text="He's completely dead!", command=root.quit) .pack(side=RIGHT, 


padx=5, pady=8) 
xf.place(relx=0.01, rely=0.125, anchor=NW) 
Label(f, text='Self-defence against fruit').place(relx=.06, rely=0.125, 
anchor=wW) 
£.pack() 


Documentation for the Frame widget starts on page 491. 
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Label 


Label widgets are used to display text or images. Labels can contain text spanning multiple 
lines, but you can only use a single font. You can allow the widget to break a string of text fit- 
ting the available space or you can embed linefeed characters in the string to control breaks. 
Several labels are shown in figure 4.5. 


(flee [Of x] 


I mean, it's a little confusing for me when 
you say ‘dog kennel’ if you want a 
mattress. Why not just say 'mattress'? 


It's not working, we need more! [rm not coming out! 








Figure 4.5 Label widget 


Although labels are not intended to be used for interacting with users, you can bind 
mouse and keyboard events to callbacks. This may be used as a “cheap” button for certain 
applications. 


Label (root, text="I mean, it's a little confusing for me when you say " 
"'dog kennel' if you want a mattress. Why not just say 'mattress'?", 
wraplength=300, justify=LEFT) .pack (pady=10) 


f£1=Frame (root) 
Label(f1, text="It's not working, we need more!", 
relief=RAISED) .pack(side=LEFT, padx=5) 
Label (f1, text="I'm not coming out!", relief=SUNKEN) .pack(side=LEFT, 
padx=5) 








f1.pack() 


£2=Frame (root) 


for bitmap,rlf in [ ('woman',RAISED), ('mensetmanus', SOLID) , 
('terminal',SUNKEN), ('escherknot',FLAT) , 
('calculator',GROOVE), ('letters',RIDGE) ]: 
Label (£2, bitmap='@bitmaps/%s' % bitmap, relief=rlf).pack(side=LEFT, 
padx=5) 
£2.pack() 


Documentation for the Label widget starts on page 495. 
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4.1.4 Button 


Strictly, buttons are labels that react to mouse and key- 
board events. You bind a method call or callback that is 
You shot him! : : : 
invoked when the button is activated. Buttons may be 
He's dead! | He's completely dead! | disabled to prevent the user from activating a button. 
Button widgets can contain text (which can span mul- 
Figure 4.6 Button widgets tiple lines) or images. Buttons can be in the tab group, 
which means that you can navigate to them using the 
TAB key. Simple buttons are illustrated in figure 4.6. 


Buttons 






Label (root, text="You shot him!") .pack(pady=10) 

Button(root, text="He's dead!", state=DISABLED) .pack(side=LEFT) 

Button(root, text="He's completely dead!", 
command=root.quit) .pack (side=RIGHT) 








Not all GUI programmers are aware that the relief option may be used to create buttons 
with different appearances. In particular, FLAT and SOLID reliefs are useful for creating toolbars 
where icons are used to convey functional information. However, some care must be exercised 
when using some relief effects. For example, if you define a button with a SUNKEN relief, the 
widget will not have a different appearance when it is activated, since the default behavior is to 
show the button with a SUNKEN relief; alternative actions must be devised such as changing the 
background color, font or wording within the button. Figure 4.7 illustrates the effect of com- 
bining the available relief types with increasing borderwidth. Note that increased borderwidth 
can be effective for some relief types (and RIDGE and GROOVE don’t work unless borderwidth 
is 2 or more). However, buttons tend to become ugly if the borderwidth is too great. 


Button 








borderwidth = 0 raised sunken flat ridge groove solid 


borderwidth = 1 raised sunken flat ridge groove 

borderwidth = 2 raised | | sunken | flat Ñ ridge groove [sid] 
borderwidth = 3 raised | | sunken flat ridge groove LCa] 
borderwidth = 4 raised | | sunken flat ridge groove Le] 


Figure 4.7 Combining relief and varying borderwidth 
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class GUI: 
def __ init__(self): 
of = [None] *5 
for bdw in range(5): 


of[bdw] = Frame(self.root, borderwidth=0) 
Label (of [bdw], text='borderwidth = %d' % bdw) .pack(side=LEFT) 
for relief in [RAISED, SUNKEN, FLAT, RIDGE, GROOVE, SOLID]: 
Button(of[bdw], text=relief, 
borderwidth=bdw, relief=relief, width=10, 
command=lambda s=self, r=relief, b=bdw: s.prt(r,b))\ 
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4.1.6 


.pack(side=LEFT, padx=7-bdw, pady=7-bdw) 
of [bdw] .pack() 
def prt(self, relief, border): 
print '%s:%d' % (relief, border) 





Documentation for the Button widget starts on page 453. 


Entry 





Entry widgets are the basic widgets used to collect input from a user. They may also be used 
to display information and may be disabled to prevent a user from changing their values. 

Entry widgets are limited to a single line of text which can be in only one font. A typical 
entry widget is shown in figure 4.8. If the text entered into the widget is longer than the avail- 
able display space, the widget scrolls the contents. You may change the visible position using 
the arrow keys. You may also use the widget’s scrolling methods to bind scrolling behavior to 
the mouse or to your application. 


eae Biel Eg 


Anagram: fra shroe! A shroe! My dingkom for a shroe!' 





Figure 4.8 Entry widget 


Label (root, text="Anagram:") .pack(side=LEFT, padx=5, pady=10) 
e = StringVar () 

Entry (root, width=40, textvariable=e) .pack(side=LEFT) 
e.set("'A shroe! A shroe! My dingkom for a shroe!'") 


Documentation for the Entry widget starts on page 484. 


Radiobutton 


eee —opq| | he Radiobutton widget may need renaming soon! It is becoming 
unusual to see car radios with mechanical button selectors, so it 
might be difficult to explain the widget to future GUI designers. 
However, the idea is that all selections are exclusive, so that selecting 
one button deselects any button already selected. 









Passion fruit 
© Loganberries 
c 


* Mangoes in syrup 


C Oranges In a similar fashion to Button widgets, Radiobuttons can dis- 
Tannie: play text or images and can have text which spans multiple lines, 
nN although in one font only. Figure 4.9 illustrates typical Radiobuttons. 


You normally associate all of the radiobuttons in a group to a 
single variable. 


Figure 4.9 
Radiobutton widget 


var = IntVar() 


for text, value in [('Passion fruit', 1), ('Loganberries', 2), 
('Mangoes in syrup', 3), ('Oranges', 4), 
('Apples', 5), ('Grapefruit', 6)]: 


Radiobutton(root, text=text, value=value, variable=var) .pack (anchor=W) 
var.set (3) 
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If the indicatoron flag is set to FALSE, the radiobutton group behaves as a button box, 
as shown in figure 4.10. The selected button is normally indicated with a SUNKEN relief. 





var = IntVar() 


for text, value in [('Red Leicester', 1), ('Tilsit', 2), ('Caerphilly', 3), 
('Stilton', 4), ('Emental', 5), 
('Roquefort', 6), ('Brie', 7)]: 


Radiobutton(root, text=text, value=value, variable=var, 
indicatoron=0) .pack(anchor=W, £1i11=X, ipadx=18) 
var.set (3) 


Radiobutton BEE 






Red Leicester 


Caerphilly 









Stilton 
Emental 


Roquefort 


Figure 4.10 Radiobuttons: indicatoron=0 


Documentation for the Radiobut ton widget starts on page 519. 


Checkbutton 


Checkbutton widgets are used to provide on/off selections for one or more items. Unlike 
radiobuttons (see “Radiobutton” on page 37) there is no interaction between checkbuttons. 
You may load checkbuttons with either text or images. Checkbuttons should normally have a 
variable (Int Var) assigned to the variable option which allows you to determine the state of 
the checkbutton. In addition (or alternately) you may bind a callback to the button which will 
be called whenever the button is pressed. 

Note that the appearance of checkbuttons is quite different on UNIX and Windows; UNIX 
normally indicates selection by using a fill color, whereas Windows uses a checkmark. The 
Windows form is shown in figure 4.11. 








Checkbutton 
M John Cleese WM Eric Idle 
I Graham Chapman WM Terry Jones 


M Michael Palin WV Terry Gilliam . : 
Figure 4.11 Checkbutton widget 


for castmember, row, col, status in [ 
('John Cleese', 0,0,NORMAL), ('Eric Idle', 0,1,NORMAL) , 
('Graham Chapman', 1,0,DISABLED), ('Terry Jones', 1,1,NORMAL), 
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('Michael Palin',2,0,NORMAL), ('Terry Gilliam', 2,1,NORMAL)]: 
setattr(var, castmember, IntVar() ) 
Checkbutton(root, text=castmember, state=status, anchor=W, 
variable = getattr(var, castmember)).grid(row=row, col=col, sticky=W) 


Documentation for the Checkbut ton widget starts on page 481. 


4.1.8 Menu 


Menu widgets provide a familiar method to allow the user to choose operations within an 
application. Menus can be fairly cumbersome to construct, especially if the cascades walk out 
several levels (it is usually best to try design menus so that you do not need to walk out more 
than three levels to get to any functionality). 

Tkinter provides flexibility for menu design, allowing multiple fonts, images and bit- 
maps, and checkbuttons and radiobuttons. It is possible to build the menu in several schemes. 
The example shown in figure 4.12 is one way to build a menu; you will find an alternate 
scheme to build the same menu online as altmenu.py. 









Button Commands Cascading Menus Checkbutton Menus Radiobutton Menus Disabled Menu 


Figure 4.12 Menu widget 


Figure 4.13 illustrated adding Button commands to menu. 


Menus 







Button Commands Cascading Menus Checkbutton Menus Radiobutton Menus Disabled Menu 








Wild Font 
oh ee 


Figure 4.13 Menu: Button commands 


mBar = Frame(root, relief=RAISED, borderwidth=2) 
mBar.pack (f£i11=X) 
CmdBtn = makeCommandMenu () 
CasBtn = makeCascadeMenu () 
ChkBtn = makeCheckbuttonMenu () 
RadBtn = makeRadiobuttonMenu () 
NoMenu = makeDisabledMenu () 
mBar.tk_menuBar(CmdBtn, CasBtn, ChkBtn, RadBtn, NoMenu) 
def makeCommandMenu () : 
CmdBtn = Menubutton(mBar, text='Button Commands', underline=0) 
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CmdBtn.pack(side=LEFT, padx="2m") 
CmdBtn.menu = Menu(CmdBtn) 


CmdBtn.menu.add_command (label="Undo" ) 
CmdBtn.menu.entryconfig(0, state=DISABLED) 


CmdBtn.menu.add_command(label='New...', underline=0, command=new_file) 
CmdBtn.menu.add_command(label='Open...', underline=0, command=open_file) 
CmdBtn.menu.add_command(label='Wild Font', underline=0, 

font=('Tempus Sans ITC', 14), command=stub_action) 
CmdBtn.menu.add_command (bitmap="@bitmaps/RotateLeft") 
CmdBtn.menu.add('separator' ) 

CmdBtn.menu.add_command(label='Quit', underline=0, 

background='white', activebackground='green', 

command=CmdBtn. quit) 











CmdBtn['menu'] = CmdBtn.menu 
return CmdBtn 


Figure 4.14 shows the appearance of Cascade menu entries. 








Tree Surgeon 
Filing Cabinet 
Goldfish 






Stockbroker 
Quantity Surveyor 


Church Warden N 
BRM 





Figure 4.14 Menu: Cascade 


def makeCascadeMenu () : 
CasBtn = Menubutton(mBar, text='Cascading Menus', underline=0) 
CasBtn.pack(side=LEFT, padx="2m") 
CasBtn.menu = Menu(CasBtn) 


CasBtn.menu.choices = Menu(CasBtn.menu) 
CasBtn.menu.choices.wierdones = Menu(CasBtn.menu.choices) 


CasBtn.menu.choices.wierdones.add_command (label='Stockbroker' ) 
CasBtn.menu.choices.wierdones.add_command(label='Quantity Surveyor') 
CasBtn.menu.choices.wierdones.add_command(label='Church Warden' ) 
CasBtn.menu.choices.wierdones.add_command(label='BRM' ) 
CasBtn.menu.choices.add_command(label='Wooden Leg' ) 
CasBtn.menu.choices.add_command(label='Hire Purchase' ) 
CasBtn.menu.choices.add_command(label='Dead Crab') 
CasBtn.menu.choices.add_command(label='Tree Surgeon' ) 
CasBtn.menu.choices.add_command(label='Filing Cabinet') 
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CasBtn.menu. 
CasBtn.menu. 
menu=CasBtn. 
CasBtn.menu. 


CasBtn['menu' ] 


choices.add_command(label='Goldfish' ) 
choices.add_cascade(label='Is it a...', 
menu.choices.wierdones) 
add_cascade(label='Scipts', 
= CasBtn.menu 


menu=CasBtn.menu.choices) 


return CasBtn 


Check buttons may be used within a menu, as shown in figure 4.15. 


Menus 






Button Commands 


Cascading Menus 





Checkbutton Menus Radiobutton Menus Disabled Menu 










v Doug 
v Stig O'Tracy 
Vince 


Gloria Pules Figure 4.15 Menu: Checkbuttons 


def makeCheckbuttonMenu () : 


ChkBtn 


Menubutton(mBar, 


text='Checkbutton Menus', underline=0) 


ChkBtn.pack(side=LEFT, padx='2m') 


ChkBtn.menu = Menu(ChkBtn) 
ChkBtn.menu.add_checkbutton(label='Doug' ) 
ChkBtn.menu.add_checkbutton(label='Dinsdale' ) 
ChkBtn.menu.add_checkbutton(label="Stig O'Tracy") 
ChkBtn.menu.add_checkbutton(label='Vince' ) 
ChkBtn.menu.add_checkbutton(label='Gloria Pules') 


ChkBtn.menu. invoke (ChkBtn.menu.index('Dinsdale') ) 
ChkBtn['menu'] = ChkBtn.menu 
return ChkBtn 
An alternative is to use Radiobuttons in a menu, as illustrated in figure 4.16. 


def makeRadiobuttonMenu() : 











RadBtn = Menubutton(mBar, text='Radiobutton Menus', underline=0) 
RadBtn.pack(side=LEFT, padx='2m') 

RadBtn.menu = Menu (RadBtn) 
RadBtn.menu.add_radiobutton(label='metonymy' ) 
RadBtn.menu.add_radiobutton(label='zeugmatists') 
RadBtn.menu.add_radiobutton(label='synechdotists') 
RadBtn.menu.add_radiobutton(label='axiomists') 
RadBtn.menu.add_radiobutton(label='anagogists') 
RadBtn.menu.add_radiobutton(label='catachresis') 
RadBtn.menu.add_radiobutton(label='periphrastic') 
RadBtn.menu.add_radiobutton(label='litotes') 
RadBtn.menu.add_radiobutton(label='circumlocutors' ) 
RadBtn['menu'] = RadBtn.menu 


return RadBtn 


TKINTER WIDGET TOUR 


41 











def makeDisabledMenu () : 
Dummy_button = Menubutton(mBar, text='Disabled Menu', underline=0) 
Dummy_button.pack(side=LEFT, padx='2m') 
Dummy_button["state"] = DISABLED 
return Dummy_button 








Documentation for the Menu widget starts on page 501. 
Documentation for the Menubut ton widget starts on page 506. 
Documentation for the Opt ionMenu class starts on page 510. 






Disabled Menu 












Button Commands Cascading Menus Checkbutton Menus Radiobutton Menus 
metonymy 
zeugmatists 
synechdotists 
axiomists 
anagogists 

v catachresis 


litotes 
circumlocutors 





Figure 4.16 Menu: Radiobuttons 


4.1.9 Message 


The Message widget provides a convenient way to present multi-line text. You can use one 
font and one foreground/background color combination for the complete message. An exam- 
ple using this widget is shown in figure 4.17. 

The widget has the standard widget methods. 


Message(root, text="Exactly. It's my belief that these sheep are laborin' " 
"under the misapprehension that they're birds. Observe their " 
"be'avior. Take for a start the sheeps' tendency to 'op about 
"the field on their 'ind legs. Now witness their attempts to " 
"fly from tree to tree. Notice that they do not so much fly " 
"as...plummet.", bg='royalblue', fg='ivory', 
relief=GROOVE) .pack(padx=10, pady=10) 


Documentation for the Message widget starts on page 508. 


Exactly. It's my belief that these sheep 
are laborin' under the misapprehension 
that they're birds. Observe their 
be'avior. Take for a start the sheeps' 


tendency to ‘op about the field on their 
'ind legs. Now witness their attmpts to 
fly from tree to tree. Notice that they do 
not so much fly as...plummet. 





Figure 4.17 Message widget 
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4.1.10 


Text 


The Text widget is a versatile widget. Its primary purpose is to display text, of course, but it 
is capable of multiple styles and fonts, embedded images and windows, and localized event 
binding. 

The Text widget may be used as a simple editor, in which case defining multiple tags and 
markings makes implementation easy. The widget is complex and has many options and meth- 
ods, so please refer to the full documentation for precise details. Some of the possible styles and 
embedded objects are shown in figure 4.18. 


Something up with my banter, chaps? 
Four hours to bury a cat? 


Can I call you "Frank"? 


What's happening Thursday then? 
Did you ELE 








this symphony in the shed? 


dare you to click on this 


I'll bite your legs off! Figure 4.18 Text widget with 
several embedded objects 





text = Text(root, height=26, width=50) 
scroll = Scrollbar(root, command=text.yview) 
text.configure (yscrollcommand=scroll.set) 


text.tag_configure('bold_italics', font=('Verdana', 12, 'bold', ‘italic')) 
text.tag_configure('big', font=('Verdana', 24, 'bold')) 
text.tag_configure('color', foreground='blue', font=('Tempus Sans ITC', 14)) 
text.tag_configure('groove', relief=GROOVE, borderwidth=2) 


text.tag_bind('bite', '<1>', 
lambda e, t=text: t.insert (END, "I'll bite your legs off!")) 


text.insert(END, 'Something up with my banter, chaps?\n') 


( 
text.insert(END, 'Four hours to bury a cat?\n', 'bold_italics') 
text.insert(END, 'Can I call you "Frank"?\n', 'big') 
text.insert(END, "What's happening Thursday then?\n", 'color') 
text.insert(END, 'Did you write this symphony in the shed?\n', 'groove') 


button = Button(text, text='I do live at 46 Horton terrace') 
text .window_create (END, window=button) 
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photo=PhotoImage(file='lumber.gif') 
text.image_create(END, image=photo) 


text.insert(END, 'I dare you to click on this\n', 'bite') 
text .pack (side=LEFT) 
scroll.pack(side=RIGHT, fi11=Y) 


Documentation for the Text widget starts on page 528. 


Canvas 


Canvases are versatile widgets. Not only can you use them to draw complex objects, using 
lines, ovals, polygons and rectangles, but you can also place images and bitmaps on the canvas 
with great precision. In addition to these features you can place any widgets within a canvas 
(such as buttons, listboxes and other widgets) and bind mouse or keyboard actions to them. 

You will see many examples in this book where Canvas widgets have been used to provide 
a free-form container for a variety of applications. The example shown in figure 4.19 is a some- 
what crude attempt to illustrate most of the available facilities. 

One property of Canvas widgets, which can be either useful or can get in the way, is that 
objects are drawn on top of any objects already on the canvas. You can change the order of can- 
vas items later, if necessary. 


$ 











Embedded Frame/Label 








Figure 4.19 Canvas widget 


canvas = Canvas(root, width =400, height=400) 
canvas.create_oval(10,10,100,100, fill='gray90') 
canvas.create_line(105,10,200,105, stipple='@bitmaps/gray3') 
canvas.create_rectangle(205,10,300,105, outline='white', fill='gray50') 
canvas.create_bitmap (355, 53, bitmap='questhead' ) 


xy = 10, 105, 100, 200 
canvas.create_arc(xy, start=0, extent=270, fill='gray60') 
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canvas.create_arc(xy, start=270, extent=5, fill='gray70') 
canvas.create_arc(xy, start=275, extent=35, fill='gray80') 
canvas.create_arc(xy, start=310, extent=49, fill='gray90') 


canvas.create_polygon(205,105,285,125,166,177,210,199,205,105, fill='white') 
canvas.create_text (350,150, text='text', fill='yellow', font=('verdana', 36) ) 


img = PhotoImage(file='img52.gif') 
canvas.create_image(145,280, image=img, anchor=CENTER) 


frm = Frame(canvas, relief=GROOVE, borderwidth=2) 
Label(frm, text="Embedded Frame/Label") .pack() 
canvas.create_window(285, 280, window=frm, anchor=CENTER) 
canvas.pack() 





Documentation for the Canvas widget starts on page 456. 
Documentation for the Bitmap class starts on page 452. 
Documentation for the PhotoImage class starts on page 512. 


Scrollbar 


meo] Scrollbar widgets can be added to any widget that supports scrolling 
such as Text, Canvas and Listbox widgets. 

Associating a Scrollbar widget with another widget is as simple 
as adding callbacks to each widget and arranging for them to be dis- 
played together. Of course, there is no requirement for them to be co- 
located but you may end up with some unusual GUIs if you don’t! Fig- 
ure 4.20 shows a typical application. 


Figure 4.20 
Scrollbar widget 


list = Listbox(root, height=6, width=15) 
scroll = Scrollbar(root, command=list.yview) 
list.configure(yscrollcommand=scroll.set) 
list.pack (side=LEFT) 
scroll.pack(side=RIGHT, fi11=Y) 
for item in range(30): 

list.insert (END, item) 





Documentation for the Scrollbar widget starts on page 525. 


Listbox 


Listbox widgets display a list of values that may be chosen by the user. The default behavior 
of the widget is to allow the user to select a single item in the list. A simple example is shown 
in figure 4.21. You may add additional bindings and use the selectmode option of the widget 
to allow multiple-item and other properties. 

See “Scrollbar” above, for information on adding scrolling capability to the listbox. 
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list = Listbox(root, width=15) 

list.pack () 

for item in range(10): 
list.insert (END, item) 


Documentation for the Listbox widget starts on page 497. 





Figure 4.21 List 
box widget 


4.1.14 Scale 


The Scale widget allows you to set linear values between selected lower and upper values and 
it displays the current value in a graphical manner. Optionally, the numeric value may be 
displayed. 

The Scale widget has several options to control its appearance and behavior; otherwise 
it is a fairly simple widget. 

The following example, shown in figure 4.22, is an adaptation of one of the demonstra- 
tions supplied with the Tcl/Tk distribution. As such, it may be useful for programmers in Tcl/ 
Tk to see how a conversion to Tkinter can be made. 


Figure 4.22 Scale widget: application 





def setHeight (canvas, heightStr): 

height = string.atoi(heightStr) 

height = height + 21 

y2 = height - 30 

if y2 < 2đů:; 
y2 = 21 

canvas.coords('poly', 
15,20,35,20,35,y2,45,y2,25,height,5,y2,15,y2,15,20) 
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4.2.1 


4.2.2 


canvas.coords('line', 
15,20,35,20,35,y2,45,y2,25,height,5,y2,15,y2,15,20) 


canvas = Canvas(root, width=50, height=50, bd=0, highlightthickness=0) 
canvas.create_polygon(0,0,1,1,2,2, fill='cadetblue', tags='poly') 
canvas.create_line(0,0,1,1,2,2,0,0, fill='black', tags='line') 


scale = Scale(root, orient=VERTICAL, length=284, from_=0, to=250, 
tickinterval=50, command=lambda h, c=canvas:setHeight (c,h) ) 

scale.grid(row=0, column=0, sticky='NE') 

canvas.grid(row=0, column=1, sticky='NWSE') 

scale.set (100) 


Documentation for the Scale widget starts on page 522. 


Fonts and colors 


The purpose of this section is to present the reader with an overview of fonts and colors as 
they apply to Tkinter. This will provide sufficient context to follow the examples that will be 
presented throughout the text. 


Font descriptors 


Those of us that have worked with X Window applications have become accustomed to the 
awkward and precise format of X window font descriptors. Fortunately, with release 8.0 and 
above of Tk, there is a solution: Tk defines font descriptors. Font descriptors are architecture 
independent. They allow the programmer to select a font by creating a tuple containing the 
family, pointsize and a string containing optional styles. The following are examples: 
('‘Arial', 12, ‘italic') 
('Helvetica', 10) 


('Verdana', 8, 'medium') 


If the font family does not contain embedded spaces, you may pass the descriptor as a sin- 
gle string, such as: 


‘Verdana 8 bold italic' 


X Window System font descriptors 


Of course, the older font descriptors are available if you really want to use them. Most X Win- 
dow fonts have a 14-field name in the form: 


-foundry-family-weight-slant-setwidth-style-pixelSize-pointSize- 
Xresolution-Yresolution-spacing-averageWidth-registry-encoding 


Normally, we only care about a few of the fields: 
-*-family-weight-slant-*-*-*-pointSize-*-*-*-*-registry-encoding 


These fields are defined as follows: 


e family AA string that identifies the basic typographic style for example, helvetica, 
arial, etc.). 
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e weight A string that identifies the nominal blackness of the font, according to the 
foundry's judgment (for example, medium, bold, etc.). 

e slant A code string that indicates the overall posture of the typeface design used in 
the font—one of roman (R), italic (I) or oblique (0). 

* pointSize An unsigned integer-string typographic metric in device-independent 
units which gives the body size for which the font was designed. 

e encoding A registered name that identifies the coded character set as defined by the 
specified registry. 


An example of an X font descriptor might be: 
'-*-verdana-medium-r-*-*-8-*-*-*-*—*-*—*! 


This describes an 8-point Verdana font, medium weight and roman (upright). Although 
the descriptor is somewhat ugly, most programmers get used to the format quickly. With X- 
servers, not all fonts scale smoothly if a specific pointsize is unavailable in a font; unfortunately 
it is a trial-and-error process to get exactly the right combination of font and size for optimal 
screen appearance. 


Colors 


Tkinter allows you to use the color names defined by the X-server. These names are quite florid, 
and do not always fully describe the color: LavenderBlush1, LemonChiffon, LightSalmon, 
MediumOrchid3 and OldLace are just a few. Common names such as red, yellow, blue and 
black may also be used. The names and the corresponding RGB values are maintained in a Tk 
include file, so the names may be used portably on any Tkinter platform.* 

It is often easier to precisely define colors using color strings: 


#RGB for 4-bit values (16 levels for each color) 
#RRGGBB for 8-bit values (256 levels for each color) 
#RRRRGGGGBBBB for 16-bit values (65526 levels for each color) 


Here is an example of how one might set up part of a color definition table for an appli- 
cation (incomplete code): 


# These are the color schemes for xxx and yyy front panels 


# Panel LED off ON Active Warning 
COLORS = [('#545454','#656565', 'LawnGreen', 'ForestGreen', 'DarkOrange',\ 
# Alarm Display Inside Chrome InsideP Chassis 

"#£L342£','#747474', '#343434', '#tefefef', '#444444','#a0a0a0',\ 
# DkChassis LtChassis VDkChassis VLtChassis Bronze 


'#767600', '#848400', '#6c6c00', '#909000', '#7e5b41'), 


etc. 





* X window color names are present in the standard X11 distribution but are not specified by the X11 
Protocol or Xlib. It is permissible for X-server vendors to change the names or alter their intepretation. 
In rare cases you may find an implementation that will display different colors with Tkinter and X 
Window applications using the same color name. 
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Setting application-wide default fonts and colors 


When designing an application, you may find that the default colors, fonts and font-sizes sup- 
plied by the system are not appropriate for the particular layout that you have in mind. At 
such times you must set their values explicitly. The values could be put right in the code (you 
will see several examples in the book where this has been done). However, this prevents end 
users or system administrators from tailoring an application to their particular requirements 
or business standards. In this case the values should be set in an external option database. For 
X window programmers this is equivalent to the resource database which is usually tailored 
using a .Xdefaults file. In fact the format of the Tk option database is exactly like the .Xde- 
faults file: 





*font: Verdana 10 
*Label*font: Verdana 10 bold 
*background: Gray80 
*Entry*background: white 
*foreground: black 

*Listbox* foreground: RoyalBlue 


The purpose of these entries is to set the font for all widgets except Labels to Verdana 
10 (regular weight) and Labels to Verdana 10 bold. Similarly we set the default colors for 
background and foreground, modifying Entry backgrounds and Listbox foregrounds. If we 
place these entries in a file called optionDB, we can apply the values using an 
option_readfile call: 


root = Tk() 
root.option_readfile('optionDB' ) 


This call should be made early in the code to ensure that all widgets are created as 
intended. 


Pmw Megawidget tour 


Python megawidgets, Pmw, are composite widgets written entirely in Python using Tkinter 
widgets as base classes. They provide a convenient way to add functionality to an application 
without the need to write a lot of code. In particular, the ComboBox is a useful widget, along 
with the Entry field with several built-in validation schemes. 





In a similar fashion to the Tkinter tour, above, the following displays show typical Pmw 
widget appearance and usage. The code is kept short and it illustrates some of the options avail- 
able for the widgets. If you need to look up a particular method or option, refer to appendix C. 
Each widget also has references to the corresponding section in the appendix. 

Pmw comes with extensive documentation in HTML format. Consequently this chapter 
will not repeat this information here. Additionally, there is example code for all of the widgets 
in the demos directory in the Pmw distribution. Most of the examples shown are simplifica- 
tions derived from that code. 

With the exception of the first example, the code examples have been stripped of the boil- 
erplate code necessary to import and initialize Tkinter. The common code which is not shown 
in any sequences after the first is shown in bold. The full source code for all of the displays is 
available online. 
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AboutDialog 


The AboutDialog widget provides a convenience dialog to present version, copyright and 
developer information. By providing a small number of data items the dialog can be displayed 
with minimal code. Figure 4.23 shows a typical AboutDialog. 


About About Dialog -ol x] 


About Dialog 


Version 1.5 
Copyright Company Name 1999 
All rights reserved 


peda 


For information about this application contact: 
Sales at Company Name 
Phone: (401) 555-1212 
email: info@company_name.com 


Figure 4.23 Pmw 
AboutDialog widget 


from Tkinter import * 

import Pmw 

root = Tk() 

root .option_readfile('optionDB' ) 
Pmw.initialise() 


Pmw.aboutversion('1.5') 
Pmw.aboutcopyright ('Copyright Company Name 1999\nAl1l rights reserved') 
Pmw.aboutcontact ( 

'For information about this application contact:\n' + 

' Sales at Company Name\n' + 

'" Phone: (401) 555-1212\n' + 

' email: info@company_name.com' 

) 


about = Pmw.AboutDialog(root, applicationname='About Dialog') 


root.mainloop() 


This widget is used in the AppShe11 class which will be presented in “A standard appli- 
cation framework” on page 155 and it is used in several examples later in the book. 
Documentation for the AboutDialog widget starts on page 542. 


Balloon 


The Balloon widget implements the now somewhat familiar balloon help motif (this is some- 
times called Tool Tips). The purpose of the widget is to display help information when the 
cursor is placed over a widget on the screen, normally after a short delay. Additionally (or 
alternatively) information may be displayed in a status area on the screen. The information in 
this area is removed after a short delay. This is illustrated in figure 4.24. 

Although balloon help can be very helpful to novice users, it may be annoying to experts. 
If you provide balloon help make sure that you provide an option to turn off output to the 
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balloon and the status area, and make such choices persistent so that the user does not have 
to turn off the feature each time he uses the application. 


balloon = Pmw.Balloon(root) 

frame = Frame(root) 

frame.pack(padx = 10, pady = 5) 

field = Pmw.EntryField(frame, labelpos=W, label_text='Name: ') 
field.setentry('A.N. Other') 

field.pack(side=LEFT, padx = 10) 


balloon.bind(field, 'Your name', ‘Enter your name') 

check = Button (frame, text='Check') 

check.pack(side=LEFT, padx=10) 

balloon.bind(check, 'Look up', 'Check if name is in the database') 
frame.pack() 








messageBar = Pmw.MessageBar(root, entry_width=40, 
entry_relief=GROOVE, 
labelpos=W, label_text='Status:') 
messageBar.pack(fill=X, expand=1, padx=10, pady=5) 


balloon.configure(statuscommand = messageBar.helpmessage) 


Balloon Help -Iof xi 


Name:|A.N. Other Check à 





Status: Check if name is in the database 














... After a few seconds 





Balloon Help -iolx] 
Name:|A.N. Other Check 
Status: Figure 4.24 Pmw 











Balloon widget 





Documentation for the Balloon widget starts on page 545. 


ButtonBox _jolx] 4.3.3 ButtonBox 


ButtonBox: The ButtonBox widget provides a convenient way to imple- 
analy | aaa | ment a number of buttons and it is usually used to provide a 
command area within an application. The box may be laid out 
either horizontally or vertically and it is possible to define a 


Figure 4.25 default button. A simple ButtonBox is shown in figure 4.25. 
Pmw ButtonBox widget 
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def buttonPress (btn): 

print 'The "$s" button was pressed' % btn 
def defaultKey (event) : 

buttonBox. invoke () 


buttonBox = Pmw.ButtonBox(root, labelpos='nw', label_text='ButtonBox: ') 
buttonBox.pack(fill=BOTH, expand=1, padx=10, pady=10) 


buttonBox.add('OK', command = lambda b='ok': buttonPress (b) ) 
buttonBox.add('Apply', command = lambda b='apply': buttonPress(b) ) 
buttonBox.add('Cancel', command = lambda b='cancel': buttonPress(b) ) 


buttonBox.setdefault('OK') 
root.bind('<Return>', defaultKey) 
root. focus_set() 
buttonBox.alignbuttons () 


Documentation for the Buttonbox widget starts on page 546. 


ComboBox 


The ComboBox widget is an important widget, originally found on Macintosh and Windows 
interfaces and later on Motif. It allows the user to select from a list of options, which, unlike 
an OptionMenu, may be scrolled to accommodate large numbers of selections. The list may 
be displayed permanently, such as the example at the left of figure 4.26 or as a dropdown list, 
shown at the right of figure 4.26. Using the dropdown form results in GUIs which require 
much less space to implement complex interfaces. 


choice = None 

def choseEntry(entry) : 
print 'You chose "%$s"' % entry 
choice.configure (text=entry) 


asply = ("The Mating of the Wersh", "Two Netlemeng of Verona", "Twelfth 
Thing", "The Chamrent of Venice", "Thamle", "Ring Kichard the Thrid") 


choice = Label(root, text='Choose play', relief='sunken', padx=20, pady=20) 
choice.pack(expand=1, fill='both', padx=8, pady=8) 


combobox = Pmw.ComboBox(root, label_text='Play:', labelpos='wn', 
listbox_width=24, dropdown=0, 
selectioncommand=choseEntry, 
scrolledlist_items=asply) 
combobox.pack(fill=BOTH, expand=1, padx=8, pady=8) 
combobox.selectitem(asply[0]) 





combobox = Pmw.ComboBox(root, label_text='Play:', labelpos='wn', 
listbox_width=24, dropdown=1, 


Documentation for the ComboBox widget starts on page 549. 
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ComboBox 2 -ol x| 


Choose play 


Play:|The Mati ifthe Wersh ¥ 
Behe Meting of the Wersh 





Twelfth Thing ComboBox 2 -iof xi 


Choose play 
Play: [Twelfth Thing 
The Mating of the Wersh 
Play: |The Mating of the Wersh x| 
i 


Two Netlemeng of Verona 
a The Mating of the Wersh 


Two Netlemeng of Verona 
Twelfth Thing 

The Chamrent of Yenice 
Thamle 

Ring Kichard the Thrid 










The Chamrent of Venice 
Thamle 
Ring Kichard the Thrid 





ComboBox 2 -ol x| 





The Chamrent of Yenice 


Play: |The Chamrent of Yenice x| 


Figure 4.26 Pmw ComboBox widget 





ComboBoxDialog 


The ComboBoxDialog widget provides a convenience dialog to allow the user to select an item 
from a ComboBox in response to a question. It is similar to a Select ionDialog widget except 
that it may allow the user to type in a value in the EntryField widget or select from a perma- 
nently displayed list or a dropdown list. An example is shown in figure 4.27. 


choice = None 

def choseEntry(entry) : 
print 'You chose "%s"' % entry 
choice.configure(text=entry) 


plays = ("The Taming of the Shrew", "Two Gentelmen of Verona", "Twelfth 

Night", "The Merchant of Venice", "Hamlet", "King Richard the Third") 

dialog = Pmw.ComboBoxDialog(root, title = 'ComboBoxDialog', 
buttons=('OK', 'Cancel'), defaultbutton='OK', 


combobox_labelpos=N, label_text='Which play?', 
scrolledlist_items=plays, listbox_width=22) 
dialog.tkraise() 


result = dialog.activate() 
print 'You clicked on', result, dialog.get() 
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ComboBoxDialog -Jol x| 
Which play? 
Twelfth ht 


The Taming of the Shrew 
Two Gentelmen of Verona 


The Merchant of Venice 
Hamlet 
King Richard the Third 





Figure 4.27 Pmw ComboBoxDialog widget 


Documentation for the ComboBoxDialog widget starts on page 551. 


4.3.6 Counter 


The Counter widget is a versatile widget which allows the user to cycle through a sequence 
of available values. Pmw provides integer, real, time and date counters and it is possible to 
define your own function to increment or decrement the displayed value. There is no limita- 
tion on the value that is displayed as the result of incrementing the counter, so there is no 
reason that the counter cannot display “eine, zwei, drei” or whatever sequence is appropriate 
for the application. Some examples are shown in figure 4.28. 


Date (4-digit year): «[[18/10/1999 >| 
| 
Integer: [56 


x| 
Real (with comma): [2,3 | 


Figure 4.28 Pmw Counter widget 





def execute (self): 
print 'Return pressed, value is', date.get() 


date = Pmw.Counter (root, labelpos=W, 
label_text='Date (4-digit year):', 
entryfield_value=time.strftime('%d/%m/%Y', 
time.localtime(time.time())), 
entryfield_command=execute, 
entryfield_validate={'validator' : 'date', 'format' : 'dmy'}, 
datatype = {'counter' : 'date', 'format' : 'dmy', ‘'yyyy' : 1}) 


real = Pmw.Counter(root, labelpos=wW, 
label_text='Real (with comma):', 
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entryfield_value='1,5', 


datatype={'counter' : 'real', 'separator' : ','}, 
entryfield_validate={'validator' : 'real', 

'min' : '=-2,0', ‘max’ ;: '5,0', 

‘separator' : ','}, 
increment= .1) 


int = Pmw.Counter(root, labelpos=Ww, 
label_text='Integer:', 
orient=VERTICAL, 
entry_width=2, 
entryfield_value=50, 





entryfield_validate={'validator' : 'integer', 
"min" » 0, ‘max’ + 99}) 
counters = (date, real) 


Pmw.alignlabels (counters) 

for counter in counters: 
counter.pack(fill=xX, expand=1, padx=10, pady=5) 
int.pack(padx=10, pady=5) 


Documentation for the Counter widget starts on page 553. 


CounterDialog 


The CounterDialog widget provides a convenience dialog requesting the user to select a 
value from a Counter widget. The counter can contain any data type that the widget is capa- 
ble of cycling through, such as the unlikely sequence shown in figure 4.29. 


LEIE AURET -ol x| 


Enter the number of twits (2 to 8) 


alla >| 
Cancel | 












Figure 4.29 Pmw CounterDialog widget 


choice = None 

dialog = Pmw.CounterDialog(root, 
label_text='Enter the number of twits (2 to 8)\n', 
counter_labelpos=N, entryfield_value=2, 
counter_datatype='numeric', 
entryfield_validate={'validator': 'numeric', 'min': 2, 'max': 8}, 
buttons=('OK', 'Cancel'), defaultbutton='OK', 
title='Twit of the Year') 

dialog.tkraise() 


result = dialog.activate() 
print 'You clicked on', result, dialog.get() 


Documentation for the CounterDialog widget starts on page 556. 
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4.3.8 Dialog 


The Dialog widget provides a simple way to create a toplevel containing a ButtonBox 
and a child site area. You may populate the child site with whatever your application requires. 
Figure 4.30 shows an example of a Dialog. 


Simple dialog 


Pmw Dialog 
Bring out your dead! 








Figure 4.30 Pmw Dialog widget 


dialog = Pmw.Dialog(root, buttons=('OK', 'Apply', 'Cancel', 'Help'), 
defaultbutton='OK', title='Simple dialog') 
w = Label(dialog.interior(), text='Pmw Dialog\nBring out your dead!', 


background='black', foreground='white', pady=20) 
w.pack(expand=1, fil1=BOTH, padx=4, pady=4) 
dialog.activate() 


Documentation for the Dialog widget starts on page 558. 


4.3.9  EntryField 


The EntryField widget is an Entry widget with associated validation methods. The built- 
in validation provides validators for integer, hexadecimal, alphabetic, alphanumeric, real, time 
and date data formats. Some of the controls that may be placed on the validation include 
checking conformity with the selected data format and checking that entered data is between 
minimum and maximum limits. You may also define your own validators. A few examples are 





shown in figure 4.31. 


ome -ol x| 


No validation [type anything here 
Real (96.0 to 107.0):[98.4 | 
Integer (5 to 42): ae) 
Date (in 2000): [20007171 i tst~™S 


Figure 4.31 Pmw EntryField widget 





noval = Pmw.EntryField(root, labelpos=W, label_text='No validation', 
validate = None) 


real = Pmw.EntryField(root, labelpos=W,value = '98.4', 
label_text = 'Real (96.0 to 107.0):', 
validate = {'validator' : 'real', 
'min' : 96, 'max' : 107, 'minstrict' : 0}) 
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int = Pmw.EntryField(root, labelpos=W, label_text = 'Integer (5 to 42):', 
validate = {'validator' : 'numeric', 
'min' : 5, 'max' : 42, ‘minstrict’ : 0}, 
value = '12') 





date = Pmw.EntryField(root, labelpos=W,label_text = 'Date (in 2000):', 
value = '2000/1/1', validate = {'validator' : 'date', 
'min' : '2000/1/1', 'max' : '2000/12/31', 
'minstrict' : 0, 'maxstrict' : 0, 
'format' : 'ymd'}) 


widgets = (noval, real, int, date) 
for widget in widgets: 

widget.pack(fill=X, expand=1, padx=10, pady=5) 
Pmw.alignlabels (widgets) 


real.component ('entry') .focus_set () 


Documentation for the EntryField widget starts on page 559. 


Group 


The Group widget provides a convenient way to place a labeled frame around a group of wid- 
gets. The label can be any reasonable widget such as a Label but it can also be an Entry- 
Field, RadioButton or CheckButton depending on the application requirements. It is also 
possible to use the widget as a graphic frame with no label. These examples are shown in 


figure 4.32. 


Group _- [oO] x] 


, place label here 


A group witha 
simple Label tag 








A group 
without a tag 


;- M checkbutton — 











Figure 4.32 Pmw Group widget 





w = Pmw.Group(root, tag_text='place label here') 
w.pack(fill=BOTH, expand=1, padx=6, pady=6) 

cw = Label(w.interior(), text='A group with a\nsimple Label tag') 
cw.pack(padx=2, pady=2, expand=1, fil1=BOTH) 


w = Pmw.Group(root, tag_pyclass=None) 

w.pack(fill=BOTH, expand=1, padx=6, pady=6) 

cw = Label(w.interior(), text='A group\nwithout a tag') 
cw.pack(padx=2, pady=2, expand=1, fil1=BOTH) 





w = Pmw.Group(root, tag_pyclass=Checkbutton, 
tag_text='checkbutton', tag_foreground='blue' ) 
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w.pack(fill=BOTH, expand=1, padx=6, pady=6) 
cw = Frame(w.interior(),width=150,height=20) 
cw.pack(padx=2, pady=2, expand=1, fi11=BOTH) 


Documentation for the Group widget starts on page 564. 


LabeledWidget 


The Labeledwidget widget is a convenience container which labels a widget or collection of 
widgets. Options are provided to control the placement of the label and control the appear- 
ance of the graphic border. The child site can be populated with any combination of widgets. 
The example shown in figure 4.33 uses the widget as a frame which requires less code than 
using individual components. 


LabeledWidget | — (Of x} 


Sunset on Cat Island 


Figure 4.33 Pmw LabeledWidget widget 


frame = Frame(root, background = 'gray80') 
frame.pack(fill=BOTH, expand=1) 


lw = Pmw.LabeledWidget (frame, labelpos='n', 
label_text='Sunset on Cat Island') 

lw.component ('hull') .configure(relief=SUNKEN, borderwidth=3) 

lw.pack (padx=10, pady=10) 


img = PhotoImage(file='chairs.gif') 
cw = Button(lw.interior(), background='yellow', image=img) 


cw.pack(padx=10, pady=10, expand=1, £1i11=BOTH) 


Documentation for the LabeledwWidget widget starts on page 565. 
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4.3.12 MenuBar 


The MenuBar widget is a manager widget which provides methods to add menu buttons and 
menus to the menu bar and to add menu items to the menus. One important convenience is 
that it is easy to add balloon help to the menus and menu items. Almost all of the menu 
options available with Tkinter Menu widgets (see “Menu” on page 39) are available through 
the Pmw MenuBar. Figure 4.34 illustrates a similar menu to the one shown in figure 4.13 
using discrete Tkinter widgets. 


Tt eg -ol x| 


Buttons Cascade Checkbutton Radiobutton 


Exit 








Figure 4.34 Pmw MenuBar widget 


balloon = Pmw.Balloon (root) 

menuBar = Pmw.MenuBar (root, hull_relief=RAISED,hull_borderwidth=1, 
balloon=balloon) 

menuBar .pack (fill=X) 


menuBar.addmenu('Buttons', 'Simple Commands') 
menuBar.addmenuitem('Buttons', 'command', 'Close this window', 
font=('StingerLight', 14), label='Close') 
menuBar.addmenuitem('Buttons', 'command', 
bitmap="@bitmaps/RotateLeft", foreground='yellow' ) 
menuBar.addmenuitem('Buttons', 'separator') 
menuBar.addmenuitem('Buttons', 'command', 


'Exit the application', label='Exit') 


menuBar.addmenu('Cascade', 'Cascading Menus') 
menuBar.addmenu('Checkbutton', 'Checkbutton Menus' ) 
menuBar.addmenu('Radiobutton', 'Radiobutton Menus') 


Documentation for the MenuBar widget starts on page 572. 


4.3.13 MessageBar 


The MessageBar widget is used to implement a status area for an application. Messages in 
several discrete categories may be displayed. Each message is displayed for a period of time 
which is determined by its category. Additionally, each category is assigned a priority so the 
message with the highest priority is displayed first. It is also possible to specify the number of 
times that the bell should be rung on receipt of each message category. Figure 4.35 shows how 
a system error would appear. 


messagebar = box = None 

def selectionCommand() : 
sels = box.getcurselection() 
if len(sels) > 0: 
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messagetype = sels[0] 
if messagetype == 'state': 
messagebar.message('state', 'Change of state message') 
else: 
text = messages [messagetype] 
messagebar.message(messagetype, text) 


messages = { 'help' : 'Save current file', 
'userevent' : 'Saving file "foo"', 
'busy' : 'Busy deleting all files from file system ... 
"systemevent': 'File "foo" saved', 
‘usererror' : ‘Invalid file name "foo/bar"', 
'systemerror': 'Failed to save file: file system full', 
} 


messagebar = Pmw.MessageBar(root, entry_width=40, entry_relief=GROOVE, 
labelpos=W, label_text='Status:') 
messagebar.pack(side=BOTTOM, fill=X, expand=1, padx=10, pady=10) 


box = Pmw.ScrolledListBox (root, listbox_selectmode=SINGLE, 
items=('state', 'help', 'userevent', 'systemevent', 
‘usererror', 'systemerror', ‘'busy',), 
label_text='Message type', labelpos=N, 
selectioncommand=selectionCommand) 
box.pack(fill=BOTH, expand=1, padx=10, pady=10) 


Documentation for the MessageBar widget starts on page 574. 


MessageBar -|O] x] 


Message type 











Status: | Failed to save file: file system full 











Figure 4.35 Pmw MessageBar widget 
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4.3.15 


MessageDialog 


The MessageDialog widget is a convenience dialog which displays a single message, which 
may be broken into multiple lines, and a number of buttons in a ButtonBox. It is useful for 
creating simple dialogs “on-the-fly.” Figure 4.36 shows an example. 


RYT som Bites] |. {OO} x] 


This dialog box was constructed on demand 


Apply | Cance | Help | Figure 4.36 Pmw 


MessageDialog widget 








dialog = Pmw.MessageDialog(root, title = 'Simple Dialog', 
defaultbutton = 0, 
buttons = ('OK', 'Apply', 'Cancel', 'Help'), 
message_text = 'This dialog box was constructed on demand') 
dialog.iconname('Simple message dialog') 


result = dialog.activate() 
print 'You selected', result 


Documentation for the MessageDialog widget starts on page 576. 


NoteBookR 


The NoteBookR widget implements the popular property sheet motif. Methods allow a num- 
ber of pages or panes to be created. Any content may then be added to the panels. The user 
selects a panel by clicking on the tab at its top. Alternatively panels may be raised or lowered 
through instance methods. An example is shown in figure 4.37. 


nb = Pmw.NoteBookR (root) 


nb.add('p1', label='Page 1') 
nb.add('p2', label='Page 2') 
nb.add('p3', label='Page 3') 


pl = nb.page('pl').interior() 
p2 = nb.page('p2') .interior() 
p3 = nb.page('p3') .interior() 


nb.pack(padx=5, pady=5, fill=BOTH, expand=1) 
Button(pl, text='This is text on page 1', fg='blue') .pack(pady=40) 


= Canvas(p2, bg='gray30') 

= c.winfo_reqwidth() 

= c.winfo_reqheight () 

.create_oval(10,10,w-10,h-10, £ill='DeepSkyBluel1' ) 

.create_text (w/2,h/2,text='This is text on a canvas', fill='white', 
font=('Verdana', 14, 'bold')) 

c.pack(fill=BOTH, expand=1) 


aagaprea 
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Notebook R -ol x| 


Page 1 | Page 2| Page 3| 


This is text on a canvas 


Figure 4.37 Pmw 
NoteBookR widget 


Documentation for the NotebookR widget starts on page 580. 


NoteBookS 


The NoteBooks widget implements an alternative style of NoteBook. NoteBooks provides 
additional options to control the color, dimensions and appearance of the tabs. Otherwise it is 
quite similar to NoteBookr. Figure 4.38 illustrates a similar layout using Notebooks. 


Notebook S -ol x| 


This is text on a canvas 


Figure 4.38 Pmw 
NoteBookS widget 


nb = Pmw.NoteBooks (root) 
nb.addPage('Page 1') 


nb.addPage('Page 2') 
nb.addPage('Page 3') 


CHAPTER 4 TKINTER WIDGETS 











4.3.17 


fl = nb.getPage('Page 1') 
f2 = nb.getPage('Page 2') 
f3 = nb.getPage('Page 3') 


nb.pack(pady=10, padx=10, fi11=BOTH, expand=1) 


Button(f1, text='This is text on page 1', fg='blue') .pack(pady=40) 


= Canvas (f2, bg='gray30') 

= c.winfo_reqwidth() 

= c.winfo_reqheight () 
.create_oval(10,10,w-10,h-10, £ill='DeepSkyBluel1' ) 


aapea 


font=('Verdana', 14, 'bold')) 
c.pack(fill=BOTH, expand=1) 


Documentation for the Notebooks widget starts on page 582. 


NoteBook 


.create_text (w/2,h/2,text='This is text on a canvas', 


fill='white', 


Release 0.8.3 of Pmw replaces NoteBookR and NoteBooks with Notebook. While it is quite 
similar to the previous notebooks, there are some small changes. In fact, you will have to make 
changes to your code to use NoteBook with existing code. However, the changes are minor 
and the new form may be a little easier to use. Figure 4.39 illustrates the new widget. 


Notebook 


Page 1 | Page 2 | Page 3 | 


This is text on a canvas 





from Tkinter import * 
import Pmw 


root = Tk() 
root.option_readfile('optionDB' ) 
root.title('Notebook' ) 
Pmw.initialise() 


nb = Pmw.NoteBook (root) 
pl = nb.add('Page 1') 
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p2 = nb.add('Page 2') 
p3 nb.add('Page 3') 
nb.pack(padx=5, pady=5, £i11=BOTH, expand=1) 


Button(pl, text='This is text on page 1', fg='blue') .pack(pady=40) 

c = Canvas (p2, bg='gray30') 

= c.winfo_reqwidth() 

= c.winfo_reqheight () 

.create_oval(10,10,w-10,h-10, fill='DeepSkyBlue1') 

.create_text (w/2,h/2,text='This is text on a canvas', fill='white', 
font=('Verdana', 14, 'bold')) 

c.pack(fill=BOTH, expand=1) 


Capg 


nb.setnaturalpagesize() 
root .mainloop () 


Documentation for the Notebook widget starts on page 578. 


OptionMenu 


The OptionMenu widget implements a classic popup menu motif familiar to Motif program- 
mers. However, the appearance of the associated popup is a little different, as shown in figure 4.40. 
OptionMenus should be used to select limited items of data. If you populate the widget with large 
numbers of data the popup may not fit on the screen and the widget does not scroll. 


OptionMenu -olx 


Choose profession: Quantity Surveyor = 





OptionMenu -of xi | 


Choose profession: Quantity St Quantity Surveyor 


Church Warden 


BRM 


OptionMenu -Iof xi 


Choose profession: Stockbroker 4 | 








Figure 4.40 Pmw OptionMenu widget 


var = StringVar () 
var.set('Quantity Surveyor') 
opt_menu = Pmw.OptionMenu(root, labelpos=w, 
label_text='Choose profession:', menubutton_textvariable=var, 
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items=('Stockbroker', 'Quantity Surveyor', 'Church Warden', 'BRM'), 
menubutton_width=16) 
opt_menu.pack(anchor=W, padx=20, pady=30) 


Documentation for the Opt ionMenu widget starts on page 584. 


PanedWidget 


The PanedWidget widget creates a manager containing multiple frames. Each frame is a con- 
tainer for other widgets and may be resized by dragging on its handle or separator line. The 
area within each pane is managed independently, so a single pane may be grown or shrunk to 
modify the layout of its children. Figure 4.41 shows an example. 


PanedWidget -Iof x] 





Figure 4.41 Pmw 
PanedWidget widget 


pane = Pmw.PanedWidget (root, hull_width=400, hull_height=300) 
pane.add('top', min=100) 
pane.add('bottom', min=100) 


topPane = Pmw. PanedWidget (pane.pane('top'), orient=HORIZONTAL) 
for num in range(4): 
if num == 
name = 'Fixed\nSize' 
topPane.add(name, min=.2, max=.2) 
else: 
name = 'Pane\n' + str(num) 
topPane.add(name, min=.1, size=.25) 
button = Button(topPane.pane(name), text=name) 
button.pack (expand=1) 
topPane.pack(expand=1, fi11=BOTH) 


pane.pack(expand=1, £1i111=BOTH) 


Documentation for the Panedwidget widget starts on page 586. 
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PromptDialog 


The PromptDialog widget is a convenience dialog which displays a single EntryField and 
a number of buttons in a ButtonBox. It is useful for creating a simple dialog on-the-fly. The 
example shown in figure 4.42 collects a password from a user. 


eres ltt Miel E 


Password: 


[ooo 


Figure 4.42 Pmw PromptDialog widget 


dialog = Pmw.PromptDialog (root, title='Password', label_text='Password:', 
entryfield_labelpos=N, entry_show='*', defaultbutton=0, 
buttons=('OK', 'Cancel')) 


result = dialog.activate() 
print 'You selected', result 


Documentation for the PromptDialog widget starts on page 587. 


RadioSelect 


The RadioSelect widget implements an alternative to the Tkinter RadioButton widget. 
RadioSelect creates a manager that contains a number of buttons. The widget may be con- 
figured to operate either in single-selection mode where only one button at a time may be 
activated, or multiple selection mode where any number of buttons may be selected. This is 
illustrated in figure 4.43. 


RadioButtons |. {Of x} 


Passion fruit | | Loganberries Mangoes in syrup | Oranges | Apples | Grapefruit | 
Doug | | Dinsdale Stig O'Tracy | | Vince Gloria Pules | 


Figure 4.43 Pmw RadioSelect widget 





horizontal 











Multiple 
selection 














horiz = Pmw.RadioSelect (root, labelpos=W, label_text=HORIZONTAL, 
frame_borderwidth=2, frame_relief=RIDGE) 
horiz.pack(fill=X, padx=10, pady=10) 





for text in ('Passion fruit', 'Loganberries', 'Mangoes in syrup', 
'Oranges', 'Apples', 'Grapefruit'): 
horiz.add(text) 
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horiz.invoke('Mangoes in syrup') 


multiple = Pmw.RadioSelect (root, labelpos=W, label_text='Multiple\nselection', 
frame_borderwidth=2, frame_relief=RIDGE, selectmode=MULTIPLE) 
multiple.pack(fill=X, padx=10) 


for text in ('Doug', 'Dinsdale', "Stig O'Tracy", 'Vince', 'Gloria Pules'): 
multiple.add(text) 


multiple.invoke('Dinsdale') 


Documentation for the RadioSelect widget starts on page 589. 


4.3.22 ScrolledCanvas 


The ScrolledCanvas widget is a convenience widget providing a Canvas widget with asso- 
ciated horizontal and vertical scrollbars. An example is shown in figure 4.44. 


ScrolledCanyas 


ScrolledCanvas 


Figure 4.44 Pmw 
ScrolledCanvas widget 





sc = Pmw.ScrolledCanvas(root, borderframe=1, labelpos=N, 
label_text='ScrolledCanvas', usehullsize=1, 
hull_width=400,hull_height=300) 


for i in range(20): 

x = -10 + 3*i 

y = -10 

for j in range(10): 
sc.create_rectangle ('%dc'%x, '%dc'%y, '%dc'%(x+2),'%dc'%(y+2), 

fill='cadetblue', outline='black' ) 
sc.create_text ('%dc'%(x+1),'%dc'%S(y+1),text='%d,%d'%(i,j), 
anchor=CENTER, fill='white') 

y=y+3 


sc.pack() 
sc.resizescrollregion() 


Documentation for the ScrolledCanvas widget starts on page 592. 
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ScrolledField 


The ScrolledField widget provides a labeled EntryField widget with bindings to allow 
the user to scroll through data which is too great to be displayed within the available space. 





This widget should be reserved for very special uses, since it contravenes many of the com- 
monly considered human factors for GUI elements. Figure 4.45 shows the effect of scrolling 
the field using the keyboard arrow keys. 














ScrolledField -iof xj ScrolledField -iof x| 


Scroll the field using the 
middle mouse button 


Scroll the field using the 
middle mouse button 








| mystical temple, surrounded by the | 


Change field | 


|ding, aloof, terrifying. This year, this | 


Change field | 


Figure 4.45 Pmw ScrolledField widget 


lines = ( 
"Mount Everest. Forbidding, aloof, terrifying. This year, this", 
"remote Himalayan mountain, this mystical temple, surrounded by the", 
"most difficult terrain in the world, repulsed yet another attempt to", 
"Conquer it. (Picture changes to wind-swept, snowy tents and people)", 
"This time, by the International Hairdresser's Expedition. In such", 
"freezing, adverse conditions, man comes very close to breaking", 
"point. What was the real cause of the disharmony which destroyed", 
"their chances at success?") 


global index 
field = index = None 
def execute(): 
global index 
field.configure(text=lines[index % len(lines) ]) 
index = index + 1 
field = Pmw.ScrolledField(root, entry_width=30, 
entry_relief=GROOVE, labelpos=N, 
label_text='Scroll the field using the\nmiddle mouse button') 
field.pack(fill=xX, expand=1, padx=10, pady=10) 





button = Button(root, text='Change field', command=execute) 
button.pack(padx=10, pady=10) 


index = 0 
execute () 


Documentation for the ScrolledField widget starts on page 594. 
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ScrolledFrame 


The ScrolledFrame widget is a convenience widget providing a Frame widget with associ- 
ated horizontal and vertical scrollbars. An example is shown in figure 4.46. 


Byer tele od olx] 


ScrolledFrame 


E) 


Figure 4.46 Pmw 
ScrolledFrame widget 





global row, col 

row = col = 0 

sf = frame = None 

def addButton(): 
global row, col 
button = Button(frame, text = '(%d,%d)' % (col, row) ) 
button.grid(row=row, col=col, sticky='nsew' ) 
frame.grid_rowconfigure(row, weight=1) 
frame.grid_columnconfigure(col, weight=1) 
sf.reposition() 


if col == row: 
col = 0 
row = row + 1 
else: 


col = col +1 


sf = Pmw.ScrolledFrame(root, labelpos=N, label_text='ScrolledFrame', 
usehullsize=1, hull_width=400, hull_height=220) 

sf.pack(padx=5, pady=3, fill='both', expand=1) 

frame = sf.interior() 


for i in range(250): 
addButton () 


Documentation for the ScrolledFrame widget starts on page 595. 
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The ScrolledListbox widget is a convenience widget providing a ListBox widget with 
associated horizontal and vertical scrollbars. Figure 4.47 shows a typical ScrolledListbox. 


Coats ee mets -iol x] 


Cast Members 


John Cleese 
Eric Idle 
Graham Chapman 


Michael Palin 


Terry Gilliam 


Figure 4.47 Pmw ScrolledListbox widget 


box = None 
def selectionCommand() : 
sels = box.getcurselection() 
if len(sels) == 
print 'No selection' 
else: 
print 'Selection:', sels[0] 


box = Pmw.ScrolledListBox(root, listbox_selectmode=SINGLE, 
items=('John Cleese', ‘Eric Idle', 'Graham Chapman', 
'Terry Jones', 'Michael Palin', 'Terry Gilliam'), 
labelpos=NW, label_text='Cast Members', 
listbox_height=5, vscrollmode='static', 
selectioncommand=selectionCommand, 
dblclickcommand=selectionCommand, 
usehullsize=1, hull_width=200, hull_height=200, ) 
box.pack(fill=BOTH, expand=1, padx=5, pady=5) 


Documentation for the ScrolledListbox widget starts on page 598. 


ScrolledText 


The Scrolledtext widget is a convenience widget providing a Text widget with associated 
horizontal and vertical scrollbars, as shown in figure 4.48. 


st = Pmw.ScrolledText (root, borderframe=1, labelpos=N, 
label_text='Blackmail', usehullsize=1, 
hull_width=400, hull_height=300, 
text_padx=10, text_pady=10, 
text_wrap='none' ) 
st.importfile('blackmail.txt') 
st.pack(fill=BOTH, expand=1, padx=5, pady=5) 


Documentation for the ScrolledText widget starts on page 600. 
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Blackmail 
lal 

‘Ello, Mrs. Teal, lovely to have you on the show. Now Mrs. Teal, if you're 
looking in tonight, this is for 15 pounds: and is to stop us from revealing 
the name of your LOVER IN BOLTON!! So, Mrs. Teal, send us 15 pounds, by 
return of post please, and your husband Trevor, and your lovely children 
Diane, Janice, and Juliet, need never know the name... of your LOVER IN 
BOLTON! 


(applause; organ music) 


Thank you Onan! And now: a letter, a hotel registration book, and a series of 
photographs, which could add up to divorce, premature retirement, and poss 
criminal proceedings for a company director in Bromsgrove. He's a freemasc 
and a conservative M.P., so that's 3,000 pounds please Mr. S... thank you... 
to stop us from revealing: 

Your name 

The name of the three other people involved, 





Figure 4.48 Pmw ScrolledText widget 


4.3.27 SelectionDialog 


The SelectionDialog widget provides a convenience dialog to allow the user to select an 
item from a ScrolledList in response to a question. It is similar to a ComboBoxDialog 
except that there is no provision for the user to type in a value. Figure 4.49 shows an example. 


EA] -of x] 


Who sells string? 





Wapcaplet 
Looseliver 
Vendetta 
Prang 





Figure 4.49 Pmw SelectionDialog widget 


dialog = None 
def execute (result): 
sels = dialog.getcurselection() 
if len(sels) == 0: 
print 'You clicked on', result, '(no selection) ' 
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else: 
print 'You clicked on', result, sels[0] 
dialog.deactivate (result) 


dialog = Pmw.SelectionDialog(root, title='String', 
buttons=('OK', 'Cancel'), defaultbutton='OK', 
scrolledlist_labelpos=N, label_text='Who sells string?', 
scrolledlist_items=('Mousebat', 'Follicle', 'Goosecreature', 
'Mr. Simpson', 'Ampersand', 'Spong', 'Wapcaplet', 
'Looseliver', 'Vendetta', 'Prang'), 
command=execute) 
dialog.activate() 


Documentation for the Select ionDialog widget starts on page 603. 


TextDialog 


The TextDialog widget provides a convenience dialog used to display multi-line text to the 
user. It may also be used as a simple text editor. It is shown in figure 4.50. 


Sketch |. {oO} xj 


The Hospital 


Doctor: Mr. Bertenshaw? 

Mr. B: Me, Doctor. 

Doctor: No, me doctor, you Mr. Bertenshaw. 

Mr. B: My wife, doctor... 

Doctor: No, your wife patient. 

Sister: Come with me, please. 

Mr. B: Me, Sister? 

Doctor: No, she Sister, me doctor, you Mr. Bertenshaw. 

Nurse: Dr. Walters? 

Doctor: Me, nurse...You Mr. Bertenshaw, she Sister, you doctor. 

Sister: No, doctor. 

Doctor: No doctor: call ambulance, keep warm. 

Nurse: Drink, doctor? 

Doctor: Drink doctor, eat Sister, cook Mr. Bertenshaw, nurse me! 

Nurse: You, doctor? 

Doctor: ME doctor!! You Mr. Bertenshaw. She Sister! 

Mr. B: But my wife, nurse... 

Doctor: Your wife not nurse. She nurse, your wife patient. Be patient, 
she nurse your wife. Me doctor, you tent, you tree, you Tarzan, me 
Jane, you Trent, you Trillo...me doctor! 





Figure 4.50 Pmw TextDialog widget 


sketch = """Doctor: Mr. Bertenshaw? 
Mr. B: Me, Doctor. 
fasses Lines removed---------- 


Jane, you Trent, you Trillo...me doctor!""" 


dialog = Pmw.TextDialog(root, scrolledtext_labelpos='n', 


CHAPTER 4 TKINTER WIDGETS 











4.3.29 


4.4 


4.4.1 





title='Sketch', 
defaultbutton=0, 
label_text='The Hospital') 
dialog.insert (END, sketch) 
dialog.configure(text_state='disabled' ) 
dialog.activate() 
dialog.tkraise() 





Documentation for the TextDialog widget starts on page 605. 


TimeCounter 


The TimeCounter widget implements a device to set hours, minutes and seconds using up 
and down arrows. The widget may be configured to autorepeat so that holding down a button 
will slew the value displayed in the widget. Figure 4.51 shows the widget’s appearance. 


àl alal 
HH:MM:ss [09/15/42 
x| 7i 7i 


Figure 4.51 Pmw TimeCounter widget 


time = Pmw.TimeCounter (root, labelpos=W, label_text='HH:MM:SS', 
min='00:00:00', max='23:59:59') 
time.pack(padx=10, pady=5) 


Documentation for the TimeCounter widget starts on page 607. 


Creating new megawidgets 


In addition to supplying useful widgets, Pmw provides a simple mechanism to allow you to 
develop new megawidgets. The documentation supplied with Pmw describes the process of 
coding a megawidget. This description is an adaptation of that material. 


Description of the megawidget 


This widget will implement a simple gauge which tracks an integer value supplied by 
D a Scale widget, which selects a number from a range. The gauge indicates the setting 
as a percentage of the range. The completed megawidget will look like the one shown 
in figure 4.52. 
The scale widget will be a component of the megawidget since the range may be 
set by the programmer; the size and color of the gauge may similarly be changed, as 
appropriate for the application, so we make this a component, too. 


Figure 4.52 Gauge widget 
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4.4.2 Options 


In addition to the options for the scale and gauge components, we will need to define some 
options for the megawidget. First, we define min and max to allow the programmer the range 
supported by the widget. Secondly, we define £111 and size to control the color and size of 
the gauge. Lastly, we define value to allow us to set the initial value of the megawidget. 


4.4.3 Creating the megawidget class 
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Pmw megawidgets inherit from either Pmw.MegaWidget, Pmw.MegaToplevel or Pmw.Dia- 
log. The gauge widget is intended to be used within other code widgets so it inherits from 
Pmw.MegaWidget. Here is the code for the megawidget. 


pmw_megawindget.py 


from Tkinter import * 
import Pmw 


class Gauge(Pmw.MegaWidget) : 
def __init__(self, parent=None, **kw): 
# Define the options for the megawidget 





optiondefs = ( 

('min', 0, Pmw. INITOPT), 
('max' 100, Pmw.INITOPT) , 
p! fill’, 'red', None) , 
('size', 30, Pmw.INITOPT) , 
('value' 0, None), 

(i skowvaiie. Ly None), 

) 


self.defineoptions(kw, optiondefs) 


# Initialize the base class 
Pmw.MegaWidget.__init__(self, parent) 


interior = self.interior() 


# Create the gauge component 


© 
© 
self.gauge = self.createcomponent ('gauge 
(), None, 
Frame, (interior,), 
borderwidth=0) 
self.canvas = Canvas(self.gauge, 
width=self['size'], height=self['size' 


background=interior.cget ('background' ) 
self.canvas.pack(side=TOP, expand=1, f£i11=BOTH) 
self.gauge.grid() 


# Create the scale component 
self.scale = self.createcomponent('scale' 
(), None, 
Scale, (interior,), 
command=self._setGauge, 
length=200, 
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from_ = self['min'], 

to = self['max'], 

showvalue=self['showvalue']) 
self.scale.grid() 


value=self['value'] 
if value is not None: 
self.scale.set (value) 


# Check keywords and initialize options 
self.initialiseoptions (Gauge) 


Q 


def _setGauge (self, value): 
self.canvas.delete ('gauge') 
ival = self.scale.get() 
ticks = self['max'] - self['min'] 
arc = (360.0/ticks) * ival 
xy = 3,3,self['size'],self['size'] 
start = 90-arce 
if start < 0: 
start = 360 + start 
self.canvas.create_arc(xy, start=start, extent=arc-.001, 
fill=self['fill'], tags=('gauge',)) 


Pmw. forwardmethods (Gauge, Scale, 'scale') QO 


root = Tk() 
root.option_readfile('optionDB' ) 
root.title('Gauge') 
Pmw.initialise() 


gl = Gauge(root, fill='red', value=56, min=0, max=255) 
gl.pack(side=LEFT, padx=1, pady=10) 





g2 = Gauge(root, fill='green', value=60, min=0, max=255) 
g2.pack(side=LEFT, padx=1, pady=10) 





g3 = Gauge(root, fill='blue', value=36, min=0, max=255) 
g3.pack(side=LEFT, padx=1, pady=10) 











root.mainloop() 





Code comments 


Options for the megawidget are specified by a three-element sequence of the option name, 
default value and a final argument. The final argument can be either a callback function, 
Pmw.INITOPT or None. If it is Pmw.INTTOPT then the option may only be provided as an 
initialization option and it cannot be set by calling configure. Calling self.defineop- 
tions includes keyword arguments passed in the widget’s constructor. These values may over- 
ride any default values. 


Having set the options we call the constructor of the base class, passing the parent widget as 
the single argument. 


By convention, Pmw defines an interior attribute which is the container for components. 
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We then create the gauge’s indicator, which is going to be drawn on a canvas contained in a 
frame. The createcomponent method has five standard arguments (name, aliases, 
group, class and arguments to the constructor) followed by any number of keyword argu- 
ments. 


Then, we construct the scale component in a similar manner. 


Having completed the constructor, we first call initialiseoptions to check that all of the 


keyword arguments we supplied have been used. It then calls any option callbacks that have 
been defined. 


Once the megawidget’s class has been defined we call the Pmw. forwardmethods method to 
direct any method calls from other widgets to the scale component. 


Gauge -iol x| 


© 2? 2 


Figure 4.53 Using the gauge megawid- 
get as a color mixer 





Figure 4.53 illustrates a possible application of the gauge megawidget as a color mixer. 
The widget may be reconfigured to show or hide the current value of each slider. It is an easy 
task to add more options to the widget. 
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Screen layout 
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5.2 Packer 79 5.5 Summary 94 
5.3 Grid 86 


GUI layout is an often-misunderstood area; a programmer could conceivably waste a lot of 
time on it. In this chapter, the three geometry managers, Pack, Grid and Place are covered 
in detail. Some advanced topics, including approaches to variable-size windows and the atten- 
dant problems of maintaining visually attractive and effective interfaces, will be presented. 


Introduction to layout 


Geometry managers are responsible for controlling the size and position of widgets on the 
screen. In Motif, widget placement is handled by one of several manager widgets. One 
example is the Constraint Widget class which includes the xmForm widget. Here, layout is 
controlled by attaching the widget by one, or more, of the top, bottom, left or right sides to 
adjacent widgets and containers. By choosing the appropriate combinations of attachments, 
the programmer can control a number of behaviors which determine how the widget will 
appear when the window is grown or shrunk. 

Tk provides a flexible approach to laying out widgets on a screen. X defines several man- 
ager class widgets but in Tk, three geometry managers may be used. In fact, it is possible to 
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use the managers with each other (although there are some rather important rules about how 
one goes about this). Tk achieves this flexibility by exploiting the X behavior that says widget 
geometry is determined by the geometry managers and not by the widgets themselves. Like X, 
if you do not manage the widget, it will not be drawn on the screen, although it will exist in 
memory. 

Geometry managers available to Tkinter are these: the Packer, which is the most com- 
monly used manager; the Grid, which is a fairly recent addition to Tk; the Placer, which has 
the least popularity, but provides the greatest level of control in placing widgets. You will see 
examples of all three geometry managers throughout the book. The geometry managers are 
available on all architectures supported by Tkinter, so it is not necessary to know anything 
about the implementation of the architecture-dependent toolkits. 


Geometry management 


Geometry management is a quite complex topic, because a lot of negotiation goes on between 
widgets, their containers, windows and the supporting window manager. The aim is to lay out 
one or more slave widgets as subordinates of a master widget (some programmers prefer to 
refer to child widgets and parents). Master widgets are usually containers such as a Frame or a 
Canvas, but most widgets can act as masters. For example, place a button at the bottom of a 
frame. As well as simply locating slaves within masters, we want to control the behavior of the 
widget as more widgets are added or when the window is shrunk or grown. 

The negotiation process begins with each slave widget requesting width and height ade- 
quate to display its contents. This depends on a number of factors. A button, for example, cal- 
culates its required size from the length of text displayed as the label and the selected font size 
and weight. 

Next, the master widget, along with its geometry manager, determines the space available 
to satisfy the requested dimensions of the slaves. The available space may be more or less than 
the requested space, resulting in squeezing, stretching or overlapping of the widgets, depending 
on which geometry manager is being employed. 

Next, depending on the design of the window, space within a master’s master must be 
apportioned between all peer containers. The results depend on the geometry manager of the 
peer widgets. 

Finally, there is negotiation between the toplevel widget (normally the toplevel shell) and 
the window manager. At the end of negotiations the available dimensions are used to deter- 
mine the final size and location in which to draw the widgets. In some cases there may not be 
enough space to display all of the widgets and they may not be realized at all. Even after this 
negotiation has completed when a window is initialized, it starts again if any of the widgets 
change configuration (for example, if the text on a button changes) or if the user resizes the 
window. Fortunately, it is a lot easier to use the geometry managers than it is to discuss them! 

A number of common schemes may be applied when a screen is designed. One of the prop- 
erties of the Packer and to a lesser extent the Grid, is that it is possible to allow the geometry 
manager to determine the final size of a window. This is useful when a window is created 
dynamically and it is difficult to predict the population of widgets. Using this approach, the win- 
dow changes size as widgets are added or removed from the display. Alternatively, the designer 
might use the Placer on a fixed-size window. It really depends on the effect that is wanted. 

Let’s start by looking at the Packer, which is the most commonly used manager. 
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5.2 Packer 


PACKER 


The Packer positions slave widgets in the master by adding them one at a time from the out- 
side edges to the center of the window. The Packer is used to manage rows, columns and com- 
binations of the two. However, some additional planning may have to be done to get the 
desired effect. 

The Packer works by maintaining a list of slaves, or the packing list, which is kept in the 
order that the slaves were originally presented to the Packer. Take a look at figure 5.1 (this fig- 
ure is modeled after John Ousterhout’s description of the Packer). 

Figure 5.1(1) shows the space available for placing widgets. This might be within a frame 
or the space remaining after placing other widgets. The Packer allocates a parcel for the next 
slave to be processed by slicing off a section of the available space. Which side is allocated is 
determined by the options supplied with the pack request; in this example, the side=LEFT and 
£i11=y options have been specified. The actual size allocated by the Packer is determined by 
a number of factors. Certainly the size of the slave is a starting point, but the available space 
and any optional padding requested by the slave must be taken into account. The allocated par- 
cel is shown in figure 5.1(2). 








































































































Master 
: H 3 
Available Space = 
P Slave g 
1 2 
Space available 
for remaining 
slaves 
3 4 
| Parcel 
5 
6 7 








Figure 5.1 Packer operation 
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Next, the slave is positioned within the parcel. If the available space 






ck - Xan 

Left | Cer eon Right | results in a smaller parcel than the size of the slave, it may be 

squeezed or cropped, depending on the requested options. In this 

Figure 5.2 Pack ge- example, the slave is smaller than the available space and its height 

ometry manager is increased to fill the available parcel. Figure 5.1(4) shows the 

available space for more slaves. In figure 5.1(5) we pack another 

slave with side=LEFT and £111=BOTH options. Again, the available parcel is larger than the 

size of the slave (figure 5.1(6)) so the widget is grown to fill the available space. The effect is 
shown in figure 5.1(7). 





Here is a simple example of using the pack method, shown in figure 5.2: 


Example_5_1.py 


from Tkinter import * 





class App: 
def __init__(self, master): 
Button (master, text='Left') .pack(side=LEFT) 
Button(master, text='Center') .pack(side=LEFT) 
Button(master, text='Right') .pack(side=LEFT) 
root = Tk() 
root.option_add('*font', ('verdana', 12, 'bold')) 


root.title("Pack - Example 1") 
display = App(root) 
root.mainloop() 





Code comments 


@ The side=LEFT argument tells the Packer to start locating the widgets in the packing list 
from the left-hand side of the container. In this case the container is the default Toplevel 
shell created by the Tk initializer. The shell shrinks or expands to enclose the packed widgets. 





Soe lolx] Enclosing the widgets in a frame has no effect 

Left | This is the Center button | Right | on the shrink-wrap effect of the Packer. In this 

example (shown in figure 5.3), we have 

Figure 5.3 Packer accommodates increased the length of the text in the middle 

requested widget sizes button and the frame is simply stretched to the 
requested size. 






Example_5 _ 2.py 


fm = Frame (master) 

Button(fm, text='Left') .pack(side=LEFT) 

Button(fm, text='This is the Center button') .pack(side=LEFT) 
Button(fm, text='Right') .pack(side=LEFT) 

fm.pack() 
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Pack - Example 2a -iol x| 
Top | Packing from the top of the frame generates the result shown 

in figure 5.4. Note that the Packer centers the widgets in the 

available space since no further options are supplied and since 


the window is stretched to fit the widest widget. 





This is the Center button 


Figure 5.4 Packing from 
the top side 


Example_5_2a.py 


Button(fm, text='Top') .pack(side=TOP) 
Button(fm, text='This is the Center button') .pack(side=TOP) 
Button(fm, text='Bottom') .pack(side=TOP) 


Combining side options in the Packer list may achieve the 
desired effect (although more often than not you'll end up with an 
effect you did not plan on!). Figure 5.5 illustrates how unusual lay- 
outs may be induced. 





Center | Right 


Figure 5.5 
Combining sides 


In all of these examples we have seen that the Packer negoti- 
ize of container. fit the requir . If 
TETTA es the overall size of containers to fit the required space. If you 





want to control the size of the container, you will have to use geom- 
etry options, because attempting to change the Frame size (see 
example_5_4.py) has no effect as shown in figure 5.6. 


Left | Center | Right 





Figure 5.6 Effect of 
changing frame size 


Example_5_4.py 


fm = Frame (master, width=300, height=200) 
Button (fm, text='Left').pack(side=LEFT) 


Sizing windows is often a problem when pro- 
grammers start to work with Tkinter (and most 
other toolkits, for that matter) and it can be frustrat- 
ing when there is no response as width and height 


Pack - Example 5 






options are added to widget specifications. 
Left | Center | Right | To set the size of the window, we have to make 
use of the wm.geometry option. Figure 5.7 shows 
the effect of changing the geometry for the root 


window. 


Figure 5.6 Assigning the geome- Example_5_5.py 


try of the Toplevel shell 
master.geometry ("300x200") 
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5.2.1 Using the expand option 


The expand option controls whether the Packer expands the widget when the window is 
resized. All the previous examples have accepted the default of expand=No. Essentially, if 
expand is true, the widget may expand to fill the available space within its parcel; whether it 
does expand is controlled by the £111 option (see “Using the fill option” on page 82). 


Pack - Example 6 Pack - Example 6a -Iof x] 





Top 
Center | 


Left | Center | Right | 









Figure 5.7 Expand without fill options 


Example_5 6.py 


Button(fm, text='Left').pack(side=LEFT, expand=YES) 
Button(fm, text='Center').pack(side=LEFT, expand=YES) 
Button(fm, text='Right').pack(side=LEFT, expand=YES) 











Figure 5.7 shows the effect of setting expand to true (YES) without using the fill option 
(see Example_5_6.py). The vertical orientation in the second screen is similar to side=TOP 
(see Example_5_2a.py). 


5.2.2 Using the fill option 


Example_5_7.py illustrates the effect of combining £111 and expand options; the output is 
shown in figure 5.9(1) 


Pack - Example 7 | — [Of x} Pack - Example 7a Pack - Example 8a 






Top 


Center | 
Bottom | 
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Figure 5.8 Using the fill option 
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Example_5_ 7.py 


Button(fm, text='Left').pack(side=LEFT, £111=xX, expand=YES) 
Button(fm, text='Center').pack(side=LEFT, £111=X, expand=YES) 
Button(fm, text='Right').pack(side=LEFT, £111=X, expand=YES) 














If the £111 option alone is used in Example_5_7.py, you will obtain a display similar to 
figure 5.9(2). By using £i11 and expand we see the effect shown in figure 5.9(3). 

Varying the combination of £111 and expand options may be used for different effects 
at different times. If you mix expand options, such as in example_5_8.py, you can allow some 
of the widgets to react to the resizing of the window while others remain a constant size. Figure 
5.10 illustrates the effect of stretching and squeezing the screen. 


Pack - Example 8 [=] EG Pack - Example 8 |. {Of x} Pack - Example 8 |_ {oOo} x 
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Figure 5.9 Allowing widgets to expand and fill independently 


Example_5 8.py 


Button(fm, text='Left').pack(side=LEFT, fill=xX, expand=NO) 
Button(fm, text='Center').pack(side=LEFT, fil1=X, expand=NO) 
Button(fm, text='Right').pack(side=LEFT, fill=X, expand=YES) 





Using £111=BoTH allows the widget to use all of its parcel. However, it might create some 
rather ugly effects, as shown in figure 5.11. On the other hand, this behavior may be exactly 
what is needed for your GUI. 


Pack - Example 9 Pack - Example 9a 


Center 





Figure 5.10 Using fill=BOTH 
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5.2.3. Using the padx and pady options 


5.2.4 


5.2.5 
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‘Left | Ge Center a Right | 


Figure 5.11 Using padx 
to create extra space 


The padx and pady options allow the widget to be packed with 
additional space around it. Figure 5.12 shows the effect of add- 
ing padx=10 to the pack request for the center button. Padding 
is applied to the specified left/right or top/bottom sides for 
padx and pady respectively. This may not achieve the effect you 
want, since if you place two widgets side by side, each with a 


padx=10, there will be 20 pixels between the two widgets and 10 pixels to the left and right of 
the pair. This can result in some unusual spacing. 


Using the anchor option 








zm“ 




















Figure 5.12 Anchoring 
a widget within the 
available space 






Pack - Example 11 


side=TOP, anchor=W | 
side=TOP, anchor=W | 
side=TOP, anchor=W | 






The anchor option is used to determine where a widget will be 
placed within its parcel when the available space is larger than 
the size requested and none or one £i11 direction is specified. 
Figure 5.13 illustrates how a widget would be packed if an 





anchor is supplied. The option anchor=CENTER positions the 
widget at the center of the parcel. Figure 5.14 shows how this 
looks in practice. 


Pack - Example 11 
side=TOP, anchor=NW 





side=TOP, anchor=W | 
side=TOP, anchor=E | 









Figure 5.13 Using the anchor option to place widgets 


Using hierarchical packing 


While it is relatively easy to use the Packer to lay out simple screens, it is usually necessary to 
apply a hierarchical approach and employ a design which packs groups of widgets within 
frames and then packs these frames either alongside one other or inside other frames. This 
allows much more control over the layout, particularly if there is a need to fill and expand the 


widgets. 


Figure 5.15 illustrates the result of attempting to lay out two columns of widgets. At first 
glance, the code appears to work, but it does not create the desired layout. Once you have 
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packed a slave using side=TOP, the remaining space is below the slave, so you cannot pack 
alongside existing parcels. 


Example_5 12.py 


fm = Frame(master) 

Button(fm, text='Top').pack(side=TOP, anchor=W, fill=X, expand=YES) 
Button(fm, text='Center').pack(side=TOP, anchor=W, fill=X, expand=YES) 
Button (fm, text='Bottom').pack(side=TOP, anchor=W, fill=X, expand=YES) 
Button(fm, text='Left') .pack(side=LEFT) 

Button(fm, text='This is the Center button') .pack(side=LEFT) 
Button(fm, text='Right') .pack(side=LEFT) 

fm.pack() 















Pack - Example 12 olx] 
Top 


Center 





Bottom 


This is the Center button 


Left 





Figure 5.14 Abusing the Packer 


All we have to do is to pack the two columns of widgets in separate frames and then pack 
the frames side by side. Here is the modified code: 


Example_5_13.py 


fm = Frame (master) 

Button(fm, text='Top').pack(side=TOP, anchor=W, fill=X, expand=YES) 
Button (fm, text='Center').pack(side=TOP, anchor=W, fill=xX, expand=YES) 
Button (fm, text='Bottom').pack(side=TOP, anchor=W, fill=X, expand=YES) 
fm.pack (side=LEFT) 
fm2 = Frame (master) 
Button(fm2, text='Left') .pack(side=LEFT) 

Button (fm2, text='This is the Center button') .pack(side=LEFT) 
Button(fm2, text='Right') .pack(side=LEFT) 

fm2.pack(side=LEFT, padx=10) 








Figure 5.16 shows the effect achieved by running Example_5_13.py. 

This is an important technique which will be seen in several examples throughout the 
book. For an example which uses several embedded frames, take a look at Examples/chapter17/ 
Example_16_9.py, which is available online. 









Pack - Example 13 |. {Oo} x] 


Left | This is the Center button Right | 


Center 


Figure 5.15 Hierarchical packing 
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5.3 Grid 


Many programmers consider the Grid geometry manager the easiest manager to use. Person- 
ally, I don’t completely agree, but you will be the final judge. Take a look at figure 5.17. This 
is a fairly complex layout task to support an image editor which uses a “by example” motif. 
Laying this out using the Packer requires a hierarchical approach with several nested Frames 
to enclose the target widgets. It also requires careful calculation of padding and other factors 
to achieve the final layout. It is much easier using the Grid. 


Image Enhancement 


Enhance 


C Focus 

C Contrast 
© Brightness 
C Color 


Variation 


[Medium Fine x| 
undo | apply | Figure 5.16 An image 


Reset | bone | enhancer using Grid 
geometry management 










Before we tackle laying out the image editor, let’s take 
a look at a simpler example. We'll create a dialog containing 


Enter New Password xÍ 








Old Password: = $ 
New Password: Ea) three labels with three entry fields, along with OK and Can- 
Enter New Password Again: | 


cel buttons. The fields need to line up neatly (the example 
is a change-password dialog). Figure 5.18 shows what the 


Ea 
Grid manager does for us. The code is quite simple, but I 


Figure 5.17 Adialog laid out — have removed some less-important lines for clarity: 
using Grid 


Example_5 14.py 


class GetPassword (Dialog) : 
def body(self, master): 
self.title("Enter New Password") 





Label (master, text='Old Password:').grid(row=0, sticky=W) 79 


Label (master, text='New Password:').grid(row=1, sticky=W) 
Label (master, text='Enter New Password Again:').grid(row=2, 
sticky=W) 
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self.oldpw = Entry(master, width = 16, show='*') 
self.newpwl = Entry (master, width = 16, show='*') 
self.newpw2 = Entry (master, width = 16, show='*') 


self.oldpw.grid(row=0, column=1, sticky=W) 
self.newpw1l.grid(row=1, column=1, sticky=W) 
self .newpw2.grid(row=2, column=1, sticky=W) 





Code comments 


First, we create the labels. Since we do not need to preserve a reference to the label, we can 
apply the grid method directly. We specify the row number but allow the column to default 
(in this case to column 0). The sticky attribute determines where the widget will be 
attached within its cell in the grid. The sticky attribute is similar to a combination of the 
anchor and expand options of the Packer and it makes the widget look like a packed widget 
with an anchor=Ww option. 


We do need a reference to the entry fields, so we create them separately. 


Finally, we add the entry fields to the grid, specifying both row and column. 


Let’s go back to the image editor example. If you plan the layout for the fields in a grid 
it is easy to see what needs to be done to generate the screen. Look at figure 5.19 to see how 
the areas are to be gridded. The important feature to note is that we need to span both rows 
and columns to set aside the space for each of the components. You may find it convenient to 
sketch out designs for complex grids before committing them to code. Here is the code for the 
image editor. I have removed some of the code, since I really want to focus on the layout and 
not the operation of the application. The full source code for this example is available online. 


o 





Figure 5.18 Designing the layout for a gridded display 
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imageEditor.py 


from Tkinter import * 
import sys, Pmw, Image, ImageTk, ImageEnhance 


class Enhancer: 
def __ init__(self, master=None, imgfile=None) : 
self.master = master 
self.masterImg = Image.open(imgfile) 
self.masterImg.thumbnail((150, 150) ) 


self.images = [None] *9 
self.imgs = [None] *9 
for i in range(9): 


© ò o 


image = self.masterImg.copy() 

self.images[i] = image 

self.imgs[i] = ImageTk.PhotoImage(self.images[i].mode, 
self.images[i].size) 


200 
for r in range(3): 
for c in range(3): 
lbl = Label(master, image=self.imgs[i]) O 
lbl.grid(row=r*5, column=c*2, 
rowspan=5, columnspan=2,sticky=NSEW, 
padx=5, pady=5) 
is=i+1 








self.original = ImageTk.PhotoImage(self.masterImg) 
Label (master, image=self.original) .grid(row=0, column=6, 
rowspan=5, columnspan=2) 





Label (master, text='Enhance', bg='gray70') .grid(row=5, column=6, 
columnspan=2, sticky=NSEW) 





self.radio = Pmw.RadioSelect (master, labelpos = None, O 
buttontype = 'radiobutton', orient = 'vertical', 
command = self.selectFunc) 

self.radio.grid(row=6, column=6, rowspan=4, columnspan=2) 

# --- Code Removed ------------------------------------------------------— 

Label (master, text='Variation', 

bg='gray70').grid(row=10, column=6, 
columnspan=2, sticky=NSWE) 
self.variation=Pmw.ComboBox (master, history=0, entry_width=11, 
selectioncommand = self.setVariation, 
scrolledlist_items=('Fine', 'Medium Fine', 'Medium', 
‘Medium Course', 'Course') ) 


self.variation.selectitem('Medium' ) 


self.variation.grid(row=11, column=6, columnspan=2) 
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Button(master, text='Undo', 
state='disabled') .grid(row=13, column=6) 


Button(master, text='Apply', 

state='disabled') .grid(row=13, column=7) 
Button(master, text='Reset', 

state='disabled') .grid(row=14, column=6) 
Button(master, text='Done', 

command=self.exit) .grid(row=14, column=7) 














# === (Code: Removed. s- aoa ss Sarasa StS ee Sr a eS Se 
root = Tk() 

root.option_add('*font', ('verdana', 10, 'bold')) 

root.title('Image Enhancement ' ) 

imgEnh = Enhancer (root, sys.argv[1]) 


root.mainloop() 





Code comments 


This example uses the Python Imaging Library (PIL) to create, display, and enhance images. 
See “Python Imaging Library (PIL)” on page 626 for references to documentation supporting 
this useful library of image methods. 


Although it’s not important in illustrating the grid manager, I left some of the PIL code in place 
to demonstrate how it facilitates handling images. Here, in the constructor, we open the master 
image and create a thumbnail within the bounds specified. PIL scales the image appropriately. 
self.masterImg = Image.open(imgfile) 
self.masterImg.thumbnail((150, 150) ) 
Next we create a copy of the image and create a Tkinter PhotoImage placeholder for each of 
the images in the 3x3 grid. 


Inside a double for loop we create a Label and place it in the appropriate cell in the grid, 
adding rowspan and columnspan options. 

lbl = Label(master, image=self.imgs[i]) 

lbl.grid(row=r*5, column=c*2, 

rowspan=5, columnspan=2,sticky=NSEW, padx=5,pady=5) 
Note that in this case the sticky option attaches the images to all sides of the grid so 

that the grid is sized to constrain the image. This means that the widget will stretch and 
shrink as the overall window size is modified. 


Similarly, we grid a label with a different background, using the sticky option to fill all of 
the available cell. 





Label (master, text='Enhance', bg='gray70') .grid(row=5, column=6, 
columnspan=2, sticky=NSEW) 


The Pmw RadioSelect widget is placed in the appropriate cell with appropriate spans: 


self.radio = Pmw.RadioSelect (master, labelpos = None, 
buttontype = 'radiobutton', orient = 'vertical', 
command = self.selectFunc) 


self.radio.grid(row=6, column=6, rowspan=4, columnspan=2) 


Finally, we place the Button widgets in their allocated cells. 
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You have already seen one example of the ImageEditor in use (figure 5.17). The real 


advantage of the grid geometry manager becomes apparent when you run the application with 


another image with a different aspect. Figure 5.20 shows this well; the grid adjusts perfectly 


to the image. Creating a similar effect using the Packer would require greater effort. 


Image Enhancement 


Enhance 


C Focus 


C Contrast 


© Brightness 


C Color 


Variation 


[Medium Fine x| 


Undo | Apply | 
Reset | Done | Figure 5.19 ImageEditor—scales for 





Figure 5.20 A simple scrapbook 
tool 
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The Placer geometry manager is the simplest of the 
available managers in Tkinter. It is considered diffi- 
cult to use by some programmers, because it allows 
precise positioning of widgets within, or relative to, 
a window. You will find quite a few examples of its 
use in this book so I could take advantage of this 
precision. Look ahead to figure 9.5 on page 213 to 
see an example of a GUI that would be fairly diffi- 
cult to implement using pack or grid. Because we 
will see so many examples, I am only going to 
present two simple examples here. 

Let’s start by creating the simple scrapbook 
window shown in figure 5.21. Its function is to dis- 
play some images, which are scaled to fit the window. 
The images are selected by clicking on the numbered 
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buttons. It is quite easy to build a little application like this; again, we use PIL to provide sup- 
port for images. 

It would be possible to use pack to lay out the window (and, of course, grid would work 
if the image spanned most of the columns) but place provides some useful behavior when 
windows are resized. The Buttons in figure 5.21 are attached to relative positions, which means 
that they stay in the same relative position as the dimensions of the window change. You 
express relative positions as a real number with 0.0 representing minimum x or y and 1.0 rep- 
resenting maximum x or y. The minimum values for the axes are conventional for window 
coordinates with x0 on the left of the screen and y0 at the top of the screen. If you run scrap- 
book.py, test the effect of squeezing and stretching the window and you will notice how the 
buttons reposition. If you squeeze too much you will cause the buttons to collide, but somehow 
the effect using place is more acceptable than the clipping that occurs with pack. Here is the 
code for the scrapbook. 


scrapbook.py 


from Tkinter import * 
import Image, ImageTk, os 


class Scrapbook: 
def __init__(self, master=None) : 
self.master = master 
self.frame = Frame(master, width=400, height=420, bg='gray50', 
relief=RAISED, bd=4) 





self.1lbl = Label (self.frame) 
self.1lbl.place(relx=0.5, rely=0.48, anchor=CENTER) 


o o 


self.images = [] 
images = os.listdir("images") 


xpos = 0.05 
for i in range(10): 

Button(self.frame, text='%d'%(i+1), bg='grayl10', 
fg='white', command=lambda s=self, img=i: \ 
s.getImg(img) ).place(relx=xpos, rely=0.99, anchor=S) 

xpos = xpos + 0.08 

self.images.append (images [i] ) 


Button(self.frame, text='Done', command=self.exit, 2» 
bg='red', fg='yellow') .place(relx=0.99, rely=0.99, anchor=SE) 


self.frame.pack() 
self.getImg(0) 
def getImg(self, img): O 


self.masterImg = Image.open(os.path.join("images", 
self.images [img] ) ) 
self.masterImg.thumbnail((400, 400) ) 

self.img = ImageTk.PhotoImage(self.masterImg) 
self.lbl['image'] = self.img 


def exit(self): 
self.master.destroy() 





root = Tk() 
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root.title('Scrapbook' ) 
scrapbook = Scrapbook (root) 
root.mainloop() 





Code comments 


We create the Label which will contain the image, placing it approximately in the center of 
the window and anchoring it at the center. Note that the relative placings are expressed as per- 
centages of the width or height of the container. 

self.lbl.place(relx=0.5, rely=0.48, anchor=CENTER) 


We get a list of files from the images directory 


place really lends itself to be used for calculated positioning. In the loop we create a Button, 
binding the index of the button to the activate callback and placing the button at the next 
available position. 


We put one button at the bottom right of the screen to allow us to quit the scrapbook. Note 
that we anchor it at the SE corner. Also note that we pack the outer frame. It is quite com- 
mon to pack a group of widgets placed within a container. The Packer does all the work of 
negotiating the space with the outer containers and the window manager. 


getImg is the PIL code to load the image, create a thumbnail, and load it into the Label. 


In addition to providing precise window placement, place also provides rubber sheet 
placement, which allows the programmer to specify the size and location of the slave window 
in terms of the dimensions of the master window. It is even possible to use a master window 
which is not the parent of the slave. This can be very useful if you want to track the dimensions 
of an arbitrary window. Unlike pack and grid, place allows you to position a window out- 
side the master (or sibling) window. Figure 5.22 illustrates the use of a window to display some 
of an image’s properties in a window above each of the images. As the size of the image changes, 
the information window scales to fit the width of the image. 


Scrapbook 





Figure 5.21 Adding a sibling window which tracks changes in attached window 
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The Placer has another important property: unlike the other Tkinter managers, it does 
not attempt to set the geometry of the master window. If you want to control the dimensions 
of container widgets, you must use widgets such as Frames or Canvases that have a config- 
ure option to allow you to control their sizes. Let’s take a look at the code needed to implement 
the information window. 


scrapbook2.py 


from 


Tkinter import * 
import Image, ImageTk, os, string 


class Scrapbook: 
def __init__(self, master=None) : 


# --- Code Removed -~-~---------- 595999 55nn nnn nnn nn nnn nnn nnn nnn nn nanan 


Button(self.frame, text='Info', command=self.info, 


bg='blue', fg='yellow') .place(relx=0.99, rely=0.90, anchor=SE) 
self.infoDisplayed = FALSE 


def getImg(self, img): 
Peel] Code Removed: Gas ae ee are rs oo So eee 


if self.infoDisplayed: 
self.info();self.info() 


def info(self): 
if self.infoDisplayed: 
self.fm.destroy() 
self.infoDisplayed = FALSE 


else: 
self.fm = Frame(self.master, bg='gray10') _9 


self.fm.place(in_=self.1lbl, relx=0.5, 
relwidth=1.0, height=50, anchor=S, 
rely=0.0, y=-4, bordermode='outside') 
ypos = 0.15 
for lattr in ['Format', 'Size', 'Mode']: 
Label(self.fm, text='%Ss:\t%s' 3 (lattr, 
getattr(self.masterImg, 

'Ss' $ string.lower(lattr))), 
bg='grayl10', fg='white', 
font=('verdana', 8)).place(relx=0.3, © 
rely= ypos, anchor=W) 

ypos = ypos + 0.35 
self.infoDisplayed = TRUE 
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Code comments 


We add a button to display the image information. 


To force a refresh of the image info, we toggle the info display. 


self.info();self.info() 
The info method toggles the information display. 
If the window is currently displayed, we destroy it. 


Otherwise, we create a new window, placing it above the image and setting its width to match 
that of the image. We also add a negative increment to the y position to provide a little 
whitespace. 


self.fm.place(in_=self.1bl, relx=0.5, 
relwidth=1.0, height=50, anchor=Ss, 
rely=0.0, y=-4, bordermode='outside' ) 


The entries in the information window are placed programmatically. 


Summary 


Mastering the geometry managers is an important step in developing the ability to produce 
attractive and effective GUIs. When starting out with Tkinter, most readers will find grid 
and pack to be easy to use and capable of producing the best results when a window is resized. 
For very precise placement of widgets, place is a better choice. However, this does take quite 
a bit more effort. 

You will see many examples of using the three managers throughout the book. Remember 
that it is often appropriate to combine geometry managers within a single window. If you do, 
you must be careful to follow some rules; if things are just not working out, then you have 
probably broken one of those rules! 
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GUI applications rely heavily on events and binding callbacks to these events in order to 
attach functionality to widgets. I anticipate that many readers may have some familiarity 
with this topic. However, this may be a new area for some of you, so I will go into some 
detail to make sure that the subject has been fully covered. Advanced topics will be discussed, 
including dynamic callback handlers, data verification techniques and “smart” widgets. 


Event-driven systems: a review 


It quite possible to build complex GUI applications without knowing anything about the 
underlying event-mechanism, regardless of whether the application is running in a UNIX, 
Windows or Macintosh environment. However, it is usually easier to develop an application 
that behaves the way you want it to if you know how to request and handle events within 
your application. 
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6.1.1 


Readers familiar with events and event handlers in X or with Windows messages might 
wish to skip ahead to look at “Tkinter events” on page 98, since this information is specific to 


Tkinter. 


What are events? 


Events are notifications (messages in Windows parlance) sent by the windowing system (the X- 
server for X, for example) to the client code. They indicate that something has occurred or 
that the state of some controlled object has changed, either because of user input or because 
your code has made a request which causes the server to make a change. 

In general, applications do not receive events automatically. However, you may not be 
aware of the events that have been requested by your programs indirectly, or the requests that 
widgets have made. For example, you may specify a command callback to be called when a but- 
ton is pressed; the widget binds an activate event to the callback. It is also possible to request 
notification of an event that is normally handled elsewhere. Doing this allows your application 
to change the behavior of widgets and windows generally; this can be a good thing but it can 
also wreck the behavior of complex systems, so it needs to be used with care. 

All events are placed in an event queue. Events are usually removed by a function called 
from the application’s mainloop. Generally, you will use Tkinter’s mainloop but it is possible 
for you to supply a specialized mainloop if you have special needs (such as a threaded appli- 
cation which needs to manage internal locks in a way which makes it impossible to use the stan- 
dard scheme). 

Tkinter provides implementation-independent access to events so that you do not need 
to know too much about the underlying event handlers and filters. For example, to detect when 
the cursor enters a frame, try the following short example: 


Example_6_1.py 


from Tkinter import * 
root = Tk() 


def enter (event): 
print 'Entered Frame: x=%d, y=%d' % (event.x, event.y) 


frame = Frame(root, width=150, height=150) 
frame.bind('<Any-Enter>', enter) # Bind event 
frame.pack () 


root .mainloop () 


The bind method of Frame is used to bind the enter callback to an Any-Enter event. 
Whenever the cursor crosses the frame boundary from the outside to the inside, the message 


will be printed. 





Ne: This example introduces an interesting issue. Depending on the speed with 

which the cursor enters the frame, you will observe that the x and y coordinates 
show some variability. This is because the x and y values are determined at the time that 
the event is processed by the event loop not at the time the actual event occurs. 
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6.1.2 


6.1.3 


Event propagation 


Events occur relative to a window, which is usually described as the source window of the 
event. If no client has registered for a particular event for the source window, the event is 
propagated up the window hierarchy until it either finds a window that a client has registered 
with, it finds a window that prohibits event propagation or it reaches the root window. If it 
does reach the root window, the event is ignored. 

Only device events that occur as a result of a key, pointer motion or mouse click are prop- 
agated. Other events, such as exposure and configuration events, have to be registered for 
explicitly. 


Event types 


Events are grouped into several categories depending on X event masks. Tk maps Windows 
events to the same masks when running on a Windows architecture. The event masks recog- 
nized by Tk (and therefore Tkinter) are shown in table 6.1. 


Table 6.1 Event masks used to group X events 





NoEventMask StructureNotifyMask Button3MotionMask 
KeyReleaseMask SubstructureNotifyMask Button5MotionMask 
ButtonReleaseMask FocusChangeMask KeymapStateMask 
LeaveWindowMask ColormapChangeMask VisibilityChangeMask 
PointerMotionHintMask KeyPressMask ResizeRedirectMask 
Button2MotionMask ButtonPressMask SubstructureRedirectMask 
Button4MotionMask EnterWindowMask PropertyChangeMask 
ButtonMotionMask PointerMotionMask OwnerGrabButtonMask 
ExposureMask Button1MotionMask 





Keyboard events 


Whenever a key is pressed, a KeyPress event is generated, and whenever a key is released, a 
KeyRelease event is generated. Modifier keys, such as SHIFT and CONTROL, generate key- 
board events. 


Pointer events 


If buttons on the mouse are pressed or if the mouse is moved, ButtonPress, ButtonRe- 
lease and MotionNoti fy events are generated. The window associated with the event is the 
lowest window in the hierarchy unless a pointer grab exists, in that case, the window that ini- 
tiated the grab will be identified. Like keyboard events, modifier keys may be combined with 
pointer events. 


Crossing events 

Whenever the pointer enters or leaves a window boundary, an EnterNotify or LeaveNo- 
tify event is generated. It does not matter whether the crossing was a result of moving the 
pointer or because of a change in the stacking order of the windows. For example, if a window 
containing the pointer is lowered behind another window, and the pointer now is in the top 
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6.2 


6.2.1 


window, the lowered window receives a LeaveNot ify event and the top window receives an 





EnterNotify event. 


Focus events 


The window which receives keyboard events is known as the focus window. FocusiIn and 
FocusOut events are generated whenever the focus window changes. Handling focus events is 
a little more tricky than handling pointer events because the pointer does not necessarily have 
to be in the window that is receiving focus events. You do not usually have to handle focus 
events yourself, because setting takefocus to true in the widgets allows you to move focus 
between the widgets by pressing the Tas key. 


Exposure events 





Whenever a window or a part of a window becomes visible, an Exposure event is generated. 
You will not typically be managing exposure events in Tkinter GUIs, but you do have the 
ability to receive these events if you have some very specialized drawing to support. 


Configuration events 


When a window's size, position or border changes, ConfigureNotify events are generated. 
A ConfigureNotify event will be created whenever the stacking order of the windows 
changes. Other types of configuration events include Gravity, Map/Unmap, Reparent and 
Visibility. 


Colormap events 


If a new colormap is installed, a ColormapNotify event is generated. This may be used by 
your application to prevent the annoying colormap flashing which can occur when another 
application installs a colormap. However, most applications do not control their colormaps 
directly. 


Tkinter events 


In general, handling events in Tkinter applications is considerably easier than doing the same 
in X/Motif, Win32 or QuickDraw. Tkinter provides convenient methods to bind callbacks to 
specific events. 


Events 
We express events as strings, using the following format: 
<modifier-type-qualifier> 


e modifier is optional and may be repeated, separated by spaces or a dash. 
e type is optional if there is a qualifier. 
e qualifier is either a button-option or a keysym and is optional if type is present. 


Many events can be described using just type, so the modifier and qualifier may 
be left out. The type defines the class of event that is to be bound (in X terms it defines the 
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event mask). Many events may be entered in a shorthand form. For example, <Key-a>, <Key- 


Press-a>, and a are all acceptable event identifiers for pressing a lower-case a. 


Here are some of the more commonly used events. You will find a complete list of events 
and keysyms in “Events and keysyms” on page 617 








Event Alt. 1 Alt2 Mod Type Qualifier Action to generate event 

<Any-Enter> Enter Enter event regardless of 
mode. 

<Button-1> ButtonPress-1 Button 1 Left mouse button click. 

<Button-2> ButtonPress-2 ButtonPress 1 Middle mouse button click. 


<B2-Motion> 


<ButtonRelease-3> 


<Configure> 


<Control-Insert> 


<Control-Shift-F3> 


<Destroy> 


<Double-Button-1> 


<Enter> 


<Expose> 


<FocusIn> 
<FocusOut> 
<KeyPress> Key 


<KeyRelease-back- 
slash> 


<Leave> 
<Map> 
<Print> 


Z 


Motion 
ButtonRe- 3 
lease 


Configure 


Insert 


F3 


Destroy 


Button Al. 


Enter 


Expose 


FocusiIn 
FocusOut 
KeyPress 


KeyRelease backslash 


Leave 
Map 


Print 


Mouse movement with 
middle mouse button down. 


Release third mouse but- 
ton 3. 


Size stacking or position has 
changed. 


Press INSERT key with Con- 
TROL key down. 


Press CONnTROL-SHIFT and F3 
keys simultaneously. 


Window is being destroyed. 


Double-click first mouse 
button 1. 


Cursor enters window. 


Window fully or partially 
exposed. 


Widget gains focus. 
Widget loses focus. 
Any key has been pressed. 


Backslash key has been 
released. 


Cursor leaves window. 

Window has been mapped. 
PRINT key has been pressed. 
Capital Z has been pressed. 








Let’s take a look at some example code that allows us to explore the event mechanism as 


it’s supported by Tkinter. 


Example_6 2.py 


from Tkinter import * 
import Pmw 


eventDict 
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'2': 'KeyPress', '3': 'KeyRelease', '4': 'ButtonPress', 





'5': 'ButtonRelease', '6': 'Motion', '7': 'Enter', 
'8': 'Leave', '9': 'FocusIn', '10': 'FocusOut', 
'12': 'Expose', '15': 'Visibility', '17': 'Destroy', O 
'18': 'Unmap', '19': 'Map', '21': 'Reparent', 
'22': 'Configure', '24': 'Gravity', '26': 'Circulate', 
'28': 'Property', '32': 'Colormap','36': 'Activate', 
'37': 'Deactivate', 
} 
root = Tk() 
def reportEvent (event): 
rpt = '\n\n%s' 3 (80*'=') 
rpt = '%s\nEvent: type=%s (%s)' % (rpt, event.type, 
eventDict.get (event.type, 'Unknown') ) O 
rpt = '%s\ntime=%s' % (rpt, event.time) 
rpt = '%s widget=%s' % (rpt, event.widget) 
rpt = '%s x=%d, y=%d'% (rpt, event.x, event.y) 
rpt = '%s x_root=%d, y_root=%d' % (rpt, event.x_root, event.y_root) 
rpt = '%s y_root=%d' % (rpt, event.y_root) 
rpt = '%s\nserial=%s' % (rpt, event.serial) 
rpt = '%s num=%s' % (rpt, event .num) 
rpt = '%s height=%s' % (rpt, event.height) 
rpt = '%s width=%s' % (rpt, event.width) 
rpt = '%s keysym=%s' % (rpt, event.keysym) 
rpt = '%s ksNum=%s' % (rpt, event .keysym_num) 





#### Some event types don't have these attributes 


try: 
rpt = '%s focus=%s' % (rpt, event.focus) 
except: Ə 
try: 
rpt = '%s send=%s' % (rpt, event.send_event) 
except: 
pass 


text2.yview (END) 
text2.insert (END, rpt) 


frame = Frame(root, takefocus=1, highlightthickness=2) 
text = Entry(frame, width=10, takefocus=1, highlightthickness=2) 
text2 = Pmw.ScrolledText (frame) 


for event in eventDict.values(): O 


o 


frame.bind('<%s>' % event, report 
text.bind('<%s>' % event, reportEvent) 








text .pack () 

text2.pack(fill=BOTH, expand=YES) 
frame.pack () 

text .focus_set () 

root.mainloop() 





CHAPTER 6 EVENTS, BINDINGS AND CALLBACKS 














Code comments 


@ eventDict defines all of the event types that Tkinter (strictly Tk) recognizes. Not all of the 
event masks defined by X are directly available to Tkinter applications, so you will see that the 
enumerated event type values are sparse. 

'12': 'Expose', '15': 'Visibility', '17': 'Destroy', 
The dictionary is also used to look up the event-type name when the event is detected. 

@  reportEvent is our event handler. It is responsible for formatting data about the event. The 
event type is retrieved from eventDict; if an unrecognized event occurs, we will type it as 
Unknown. 
def reportEvent (event): 

rpt = '\n\n%s' % (80*'=') 
rpt = '%s\nEvent: type=%s (%s)' % (rpt, event.type, 
eventDict.get(event.type, 'Unknown') ) 

© Not all events supply focus and send_event attributes, so we handle AttributeErrors 
appropriately. 

© Finally, we bind each of the events to the reportEvent callback for the Frame and Entry 
widgets: 
for event in eventDict.values(): 


frame.bind('<%s>' % event, reportEvent) 
text.bind('<%s>' % event, reportEvent) 


Figure 6.1 shows the result of running Example_6_2.py. The displayed events show the 
effect of typing SHIFT-M. You can see the KeyPress for the SHIFT key, and the KeyPress for 
the M key, followed by the corresponding KeyRelease events. 


1A -iolxi 


Event: type=2 (KeyPress] 
time=95763410 widget=.8654512.8653712 x=19, y=13 x_toot=516, y root=169 y root=169 
serial=2092 num=16 height=0 width=0 keysym=Shift_L ksNum=65505 


Event: type=2 (KepPress) 
time=95763590 widget=.8654512.8653712 x=19, y=13 x_root=516, y root=169 y root=169 
setial=2117 num=77 height=0 width=0 keysym=M ksNum=77 


Event: type=3 (KeyRelease) 
time=95763670 widget=.8654512.8653712 x=19, y=13 x_root=516, y root=169 y_root=169 
serial=2143 num=?77 height=0 width=0 keysym=M ksNum=7? send=0 


Event: type=3 (KeyRelease) 
time=95763730 widget=.8654512.8653712 x=19. y=13 x_toot=516, y_root=169 y _root=169 
serial=2166 num=16 height=0 width=0 keysym=Shift_L ksNum=65505 send=0 


Event: type=6 (Motion) 
time=95763771 widget=.9654512.8653712 x=19, y=14 x_root=516, y root=170 y root=170 Figure 6.1 An event 
serial=2189 num=256 height=0 width=0 keysym=?? ksNum=0 send=0 g 6 





monitor 
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Ne: If you are new to handling events, you might find it useful to run 

Example_6_2.py to investigate the behavior of the system as you perform some 
simple tasks in the window. For example, holding the SHIFT key down creates a stream of 
events; moving the mouse creates a stream of motion events at an even greater frequency. 

This may come as a surprise initially, since the events are normally invisible to 
the user (and to the programmer). It is important to be aware of this behavior and as you 
program to take account of how events will actually be generated. It is especially impor- 
tant to make sure that the callback does not do any intensive processing; otherwise, it is 
easy to cause severe performance problems. 





Callbacks 


Callbacks are simply functions that are called as the result of an event being generated. Han- 
dling arguments, however, can be problematic for beginning Tkinter programmers, and they 
can be a source of latent bugs, even for seasoned programmers. 

The number of arguments depends on the type of event that is being processed and 
whether you bound a callback directly or indirectly to an event. Here is an example of an indi- 
rect binding: 


btn = Button(frame, text='OK', command=buttonAction) 


command is really a convenience function supplied by the Button widget which calls the 
buttonAction callback when the widget is activated. This is usually a result of a <Button- 
Press-1> event, but a <KeyPress-space> is also valid, if the widget has focus. However, 
be aware that many events have occurred as a result of moving and positioning the mouse 
before the button was activated. 

We could get the same effect by binding directly: 


btn.bind('<Button-1>', buttonAction) 
btn.bind('<KeyPress-space>', buttonAction) 


So what is the difference? Well, apart from the extra line of code to bind the events directly, 
the real difference is in the invocation of the callback. If the callback is invoked from the event, 
the event object will be passed as the first (in this case the only) argument of the callback. 





Ne: Event handlers can be a source of latent bugs if you don’t completely test your 

applications. If an event is bound (intentionally or erroneously) to a callback 
and the callback does not expect the event object to be passed as an argument, then the 
application could potentially crash. This is more likely to happen if the event rarely 
occurs or is difficult to simulate in testing. 





If you want to reuse but tonAction and have it called in response to both direct and indirect 
events, you will have to write the callback so that it can accept variable arguments: 


def buttonAction(event=None) : 


if event: 
print ‘event in: %s' % event.type 
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else: 
print ‘command in:' 


Of course, this does increase complexity, particularly if the function already has arguments, 
since you will have to determine if the first argument is an event object or a regular argument. 


6.4 Lambda expressions 


Oh no! Not the dreaded lambda again!* Although lambda has been mentioned earlier in the 
book, and has been used extensively in examples, before we go on to the next section we must 
take another look at the use of lambda. 

The term /ambda originally came from Alonzo Church’s lambda calculus and you will 
now find lambda used in several contexts—particularly in the functional programming disci- 
plines. Lambda in Python is used to define an anonymous function which appears to be a state- 
ment to the interpreter. In this way you can put a single line of executable code where it would 
not normally be valid. 

Take a look at this code fragment: 


var = IntVar() 
value = 10 


btn.bind('Button-1', (btn.flash(), var.set (value) ) ) 


A quick glance at the bolded line might not raise any alarms, but the line will fail at run- 
time. The intent was to flash the button when it was clicked and set a variable with some pre- 
determined value. What is actually going to happen is that both of the calls will be called when 
the bind method executes. Later, when the button is clicked, we will not get the desired effect, 
since the callback list contains just the return values of the two method calls, in this case 
(None, None). Additionally, we would have missed the event object—which is always the first 
argument in the callback—and we could possibly have received a runtime error. Here is the 
correct way to bind this callback: 


btn.bind('Button-1', lambda event, b=btn, v=var, i=value: 
(b.flash(), v.set(i))) 


Notice the event argument (which is ignored in this code fragment). 


6.4.1 Avoiding lambdas altogether 


If you don’t like lambda expressions, there are other ways of delaying the call to your func- 
tion. Timothy R. Evans posted a suggestion to the Python news group which defines a com- 
mand class to wrap the function. 


class Command: 
def __ init__(self, func, *args, **kw): 
self.func = func 
self.args = args 





* “Cardinal Fang! Bring me the lambda!” 
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self.kw = kw 


def call__(self, *args, **kw): 


args = self.args + args 
kw.update (self .kw) 
apply(self.func, args, kw) 


Then, you define the callback like this: 


Button (text='label', command=Command(function, arg [, moreargs...] )) 


The reference to the function and arguments (including keywords) that are passed to the 
Command class are stored by its constructor and then passed on to the function when the call- 
back is activated. This format for defining the callbacks may be a little easier to read and main- 
tain than the lambda expression. At least there are alternatives! 


Binding events and callbacks 


The examples so far have demonstrated how to bind an event handler to an instance of a wid- 
get so that its behavior on receiving an event will not be inherited by other instances of the 
widget. Tkinter provides the flexibility to bind at several levels: 


1 At the application level, so that the same binding is available in all windows and widgets 
in the application, so long as one window in the application has focus. 
2 At the class level, so that all instances of widgets have the same behavior, at least initially. 
3 At the shell (Toplevel or root) level. 
4 At the instance level, as noted already. 
Binding events at the application and class level must be done carefully, since it is quite 
easy to create unexpected behavior in your application. In particular, indiscriminate binding 


at the class level may solve an immediate problem, but cause new problems when new func- 
tionality is added to the application. 





No It is generally good practice to avoid creating highly nonstandard behavior in 

widgets or interfaces with which the user is familiar. For example, it is easy to 
create bindings which allow an entry field to fill in reverse (so typing 123 is displayed as 
321), but this is not typical entry behavior and it might be confusing to the user. 





Bind methods 


You will find more information on bind and unbind methods in “Common options” on 
page 425, so in this section, I will just illustrate bind methods in the context of the four bind- 
ing levels. 


Application level 


Applications frequently use F1 to deliver help. Binding this keysym at the application level 
means that pressing Fl, when any of the application’s windows have focus, will bring up a 
help screen. 
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Class level 


Binding at the class level allows you to make sure that classes behave uniformly across an 
application. In fact, Tkinter binds this way to provide standard bindings for widgets. You will 
probably use class binding if you implement new widgets, or you might use class binding to 
provide audio feedback for entry fields across an application, for example. 


Toplevel window level 


Binding a function at the root level allows an event to be generated if focus is in any part of a 
shell. This might be used to bind a print screen function, for example. 


Instance level 


We have already seen several examples of this, so we will not say any more at this stage. 
The following hypothetical example illustrates all four of the binding modes together. 


Example_6_ 3.py 


from Tkinter import * 
def displayHelp(event): 


def displayHelp(event): 
print 'hlp', event.keysym 


def sayKey (event): 
print 'say',event.keysym, event.char 


def printWindow(event) : 
print 'prt', event.keysym 


def cursor(*args): 
print 'cursor' 





def unbindThem(*args) :  ) unbind all bindings 
root.unbind_all('<F1>') 
root.unbind_class('Entry', '<KeyPress>') 





root.unbind('<Alt_L>') 
frame.unbind('<Control-Shift-Down>' ) 
print 'Gone...' 





root = Tk() 
frame = Frame(root, takefocus=1, highlightthickness=2) 
text = Entry(frame, width=10, takefocus=1, highlightthickness=2) 


root.bind_all('<F1>', displayHelp) 





text.bind_class('Entry', '<KeyPress>', lambda e, x=101: sayKey(e,x) ) 0 
root.bind('<Alt_L>', printWindow) O 
frame.bind('<Control-Shift-Down>' , cursor) 


text.bind('<Control-Shift-Up>', unbindThem) 
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text .pack () 
frame.pack () 
text .focus_set () 
root.mainloop() 





Code comments 


First, the callbacks are defined. These are all simple examples and all but the last one take 
account of the event object being passed as the callback’s argument, from which we extract 
the keysym of the key generating the event. 


def displayHelp(event): 
print 'hlp', event.keysym 





Although the class-level binding was made with a method call to an Entry widget, 
bind_class is an inherited method, so any instance will work and root .unbind_class is 
quite acceptable. This is not true for an instance binding, which is local to the instance. 
We make an application-level binding: 
root.bind_all('<F1>', displayHelp) 
In this class-level binding we use a lambda function to construct an argument list for the callback: 
text.bind_class('Entry', '<KeyPress>', lambda e, x=101: sayKey(e,x) ) 
Here we make a toplevel binding for a print-screen callback: 
root.bind('<Alt_L>', printWindow) 
Finally, we make instance bindings with double modifiers: 


frame.bind('<Control-Shift-Down>', cursor) 
text.bind('<Control-Shift-Up>', unbindThem) 





Note Be prepared to handle multiple callbacks for events if you use combinations of 
the four binding levels that have overlapping bindings. 
Tkinter selects the best binding at each level, starting with any instance bind- 
ings, then toplevel bindings, followed by any class bindings. Finally, application level 
bindings are selected. This allows you to override bindings at any level. 





Handling multiple bindings 


As I mentioned in the note above, you can bind events at each of the four binding events. 
However, because events are propagated, that might not result in the behavior that you 
intended. 

For a simple example, suppose you want to override the behavior of a widget, and rather 
than have BACKSPACE remove the previous character, you want to insert \h into the widget. So 
you set up the binding like this: 


text.bind('<BackSpace>', lambda e: dobackspace(e) ) 
and define the callback like this: 


def dobackspace (event) : 





event.widget.insert (END, '\\h') 
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Unfortunately this doesn’t work, because the event is bound at the application level. The 
widget still has a binding for BACKSPACE, so after the application level has been invoked and 
\h has been inserted into the widget, the event is propagated to the class level and the h is 
removed. 

There is a simple solution: return “break” from the last event handler that you want to 
propagate events from and the superior levels don’t get the event. So, the callback looks like this: 


def dobackspace(event) : 
event.widget.insert (END, '\\h') 


return "break" 


6.6 Timers and background procedures 


The mainloop supports callbacks which are not generated from events. The most important 
result of this is that it is easy to set up timers which call callbacks after a predetermined delay 
or whenever the GUI is idle. Here is a code snippet from an example later in the book: 


if self.blink: 
self.frame.after(self.blinkrate * 1000, self.update) 


def update(self): 
# Code removed 
self.canvas.update_idletasks () 
if self.blink: 
self.frame.after(self.blinkrate * 1000, self.update) 


This code sets up to call self .update after self.blinkrate * 1000 milliseconds. The 
callback does what it does and then sets up to call itself again (these timers are called once 
only—if you want them to repeat you must set them up again). 

For more information on timers, see “Common options” on page 425. 


6.7 Dynamic callback handlers 


A single callback is frequently bound to an event for the duration of an application. However, 
there are many cases where we need to change the bindings to the widget to support applica- 
tion requirements. One example might be attaching a callback to remove reverse video (that 
was applied as the result of a validation error) on a field when a character is input. 

Getting dynamic callbacks to work is simply a matter of binding and unbinding events. 
We saw examples of this in Example_6_3.py on page 105, and there are other examples in the 
source code. 





Ne: If you find that you are constantly binding and unbinding events in your code, 

it may be a good idea to review the reasons why you are doing this. Remember 
that events can be generated in rapid succession—mouse movement, for example, gener- 
ates a slew of events. Changing bindings during an event storm may have unpredictable 
results and can be very difficult to debug. Of course, we burn CPU cycles as well, so it 
can have a considerable effect on application performance. 
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6.8 Putting events to work 


In several of the early chapters, we saw examples of setting widgets with data and of getting 
that data and using it in our applications. In “Dialogs and forms” on page 140, we will see 
several schemes for presenting and getting data. This is an important topic that may require 
some ingenuity on your part to devise correct behavior. In the next few paragraphs, I'll 
present some ideas to help you solve your own requirements. 


6.3.1 Binding widgets to dynamic data 


Tkinter provides a simple mechanism to bind a variable to a widget. However, it not possible 
to use an arbitrary variable. The variable must be subclassed from the Variable class; several 
are predefined and you could define your own, if necessary. Whenever the variable changes, 
the widget’s contents are updated with the new value. Look at this simple example: 


Example_6_4.py 


from Tkinter import * 
root = Tk() 


class Indicator: 
def __init__(self, master=None, label='', value=0): 
self.var = BooleanVar () 
self.i = Checkbutton(master, text=label, variable = self.var, 
command=self.valueChanged) 
self.var.set (value) 
self.i.pack() 


def valueChanged (self): 
print 'Current value = %s' % ['Off','On'][self.var.get()] 


ind = Indicator (root, label='Furnace On', value=1) 
root.mainloop() 


This example defines self . var and binds it to the widget’s variable; it also defines a call- 
back to be called whenever the value of the widget changes. In this example the value is changed 
by clicking the checkbutton—it could equally be set programmatically. 

Setting the value as a result of an external change is a reasonable scenario, but it can intro- 
duce performance problems if the data changes rapidly. If our GUI contained many widgets 
that displayed the status and values of components of the system, and if these values changed 
asynchronously (for instance, each value arrived in the system as SNMP traps), the overhead 
of constantly updating the widgets could have an adverse effect on the application’s perfor- 
mance. Here is a possible implementation of a simple GUI to monitor the temperature 
reported by ten sensors. 


Example_6_5.py 


from Tkinter import * 
import random 
root = Tk() 
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class Indicator: 
def __init__(self, master=None, label='', value=0.0): 


self.var = DoubleVar() 


© © 


self.s = Scale (master, label=label, variable=self.var, 


from_=0.0, to=300.0, orient=HORIZONTAL, 


length=300) 
self.var.set (value) © 
self.s.pack() 
def setTemp(): 
slider = random.choice(range(10)) © 
value = random.choice(range(0, 300)) 


slist[slider] .var.set (value) 


© O 


root.after(5, setTemp) 


slist = [] 
for i in range(10): 
slist.append(Indicator(root, label='Probe %d' % (i+1))) 


setTemp () o 
root.mainloop() 





Code comments 
First we create a Tkinter variable. For this example we store a real value: 
self.var = DoubleVar() 
We then bind it to the Tk variable: 
self.s = Scale(master, label=label, variable=self.var, 
Then we set its value. This immediately updates the widget to display the new value: 
self.var.set (value) 
The purpose of the set Temp function is to create a value randomly for one of the “sensors” at 
5 millisecond intervals. 
The variable is updated for each change: 
slist[slider] .var.set (value) 
Since after is a one-shot timer, we must set up the next timeout: 
root.after(5, setTemp) ’ 


The call to set Temp starts the simulated stream of sensor information. 


The display for this example is not reproduced here (the code is available online, of 
course). However, the display’s behavior resembles Brownian motion, with widgets con- 
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stantly displaying new values. In a “real” application, the update rate would be annoying to the 
user, and it requires throttling to create a reasonable update rate. Additionally, constantly 
redrawing the widgets consumes an exceptionally high number of CPU cycles. Compare 


Example_6_5.py with the code for Example_6_6.py. 


Example_6_ 6.py 


from Tkinter import * 
import random 
root = Tk() 


class Indicator: 
def __init__(self, master=None, label='', value=0.0): 

self.var = DoubleVar () 

self.s = Scale(master, label=label, variable=self.var, 
from_=0.0, to=300.0, orient=HORIZONTAL, 
length=300) 

self.value = value o 

self.var.set (value) 

self.s.pack() 

self.s.after(1000, self.update) 


def set(self, value): 
self.value = value 


self.var.set (self.value) 
self.s.update_idletasks() 
self.s.after(1000, self.update) 


def update(self): 


def setTemp(): 
slider = random.choice(range(10) ) 
value = random.choice(range(0, 300)) 
slist [slider] .set (value) O 
root.after(5, setTemp) 


slist = [] 
for i in range(10): 
slist.append(Indicator(root, label='Probe %d' % (i+1))) 
setTemp () 
root.mainloop() 





Code comments 


@ In addition to the Tkinter variable, we create an instance variable for the widgets current 
value: 


self.value = value 


@ An after timeout arranges for the update method to be called in one second: 
self.s.after(1000, self.update) 


© The class defines a set method to set the current value. 
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The update method sets the Tkinter variable with the current value, updating the widget’s 
display. To redraw the widgets, we call update_idletasks which processes events waiting 
on the event queue. 


self.s.update_idletasks () 


@ Now, when the value changes, we set the instance variable: 


slist[slider] .set (value) 


The display now updates the widgets once a second, which results in a more relaxed dis- 
play and noticeably lowers the CPU overhead. You can optimize the code more, if you wish, 
to further reduce the overhead. For example, the widgets could be updated from a single update 
timeout rather than from a one-per-widget call. 


Pmw EntryField Validation |- lo} x] 


Date (mm/dd/yy): [szozz199 
Time (24hr clock): [e:00:00 
Real (50.0 to 1099.0):[127.2 
Social Security #: foro-11f ti (iti‘t:™*S 


Quit Figure 6.2 Validating entry 
fields (Example_6_7.py) 





6.8.2 Data verification 


An important part of a GUI, which performs data entry, is verifying appropriate input values. 
This area can consume a considerable amount of time and effort for the programmer. There 
are several approaches to validating input, but we will not attempt to cover all of them here. 

Pmw EntryField widgets provide built-in validation routines for common entryfield 
types such as dates, times and numeric fields. Using these facilities can save you a considerable 
amount of time. Here is a simple example of using Pmw validation: 


Example_6_7.py 


import time, string 
from Tkinter import * 
import Pmw 


class EntryValidation: 
def __init__(self, master): 
now = time.localtime(time.time() ) 
self._date = Pmw.EntryField(master, 





labelpos = 'w', label_text = 'Date (mm/dd/yy):', 
value = '%d/%d/%d' % (now[1], now[2], now[0]), 
validate = {'validator':'date', 

'format':'mdy', 'separator':'/'}) © 
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self._time = Pmw.EntryField(master, 
labelpos = 'w', label_text = 'Time (24hr clock):', 
value = '8:00:00', 
validate = {'validator':'time', 
'min':'00:00:00', 'max':'23:59:59', 
'minstrict':0, 'maxstrict':0}) 


self._real = Pmw.EntryField (master, 


labelpos = 'w',value = '127.2', 
label_text = 'Real (50.0 to 1099.0):', 
validate = {'validator':'real', ® sup real 
'min':50, 'max':1099, 
'minstrict':0}, 
modifiedcommand = self.valueChanged) 
self._ssn = Pmw.EntryField(master, 
labelpos = 'w', label_text = 'Social Security #:', 
validate = self.validateSSN, value = '') (3) 
fields = (self._date, self._time, self._real, self._ssn) 


for field in fields: 
field.pack(fill='x', expand=1, padx=12, pady=8) 


Pmw.alignlabels (fields) O 
self._date.component ('entry').focus_set() 


def valueChanged (self): 
print 'Value changed, value is', self._real.get() 
def validateSSN(self, contents): 
result = -1 
if '-' in contents: _9 
ssnf = string.split(contents, '-') 
try: 
if len(ssnf[0]) == 3 and \ 
len(ssnf[1]) == 2 and \ 
len(ssnf[2]) == 4: 
result = 1 
except IndexError: 
result = -1 
elif len(contents) == 9: 
result = 
return result 


1 





__name__ == '_ main_': 

root = Tk() 

root.option_add('*Font', 'Verdana 10 bold') 
root.option_add('*EntryField.Entry.Font', 'Courier 10') 
root.option_add('*EntryField.errorbackground', 'yellow') 
Pmw.initialise(root, useTkOptionDb=1) 





root.title('Pmw EntryField Validation' ) 

quit = Button(root, text='Quit', command=root.destroy) 
quit.pack(side = 'bottom') 

top = EntryValidation (root) 

root.mainloop() 
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Code comments 


The date field uses the built-in date validator, specifying the format of the data and the 
separators: 
validate = {'validator':'date', 
'format':'mdy', 'separator':'/'}) 
The time field sets maximum and minimum options along with minstrict and maxstrict: 
validate = {'validator':'time', 
'min':'00:00:00', 'max':'23:59:59', 
'minstrict':0, 'maxstrict':0}) 
Setting minstrict and maxstrict to False (zero) allows values outside of the min 
and max range to be set. The background will be colored to indicate an error. If they are set to 
True, values outside the range cannot be input. 


The Social Security field uses a user-supplied validator: 

validate = self.validateSSN, value = '') 
Pmw provides a convenience method to align labels. This helps to reduce the need to set up 
additional formatting in the geometry managers. 


Pmw.alignlabels (fields) 
self._date.component('entry') .focus_set () 


It is always a good idea to set input focus to the first editable field in a data-entry screen. 


The validatessn method is simple; it looks for three groups or characters separated by 
dashes. 


Since the entry is cumulative, the string.split call will fail until the third group has been 
entered. 


We set the Tk options database to override fonts and colors in all components used in 
the Pmw widgets. 





root.option_add('*Font', 'Verdana 10 bold') 
root.option_add('*EntryField.Entry.Font', 'Courier 10') 
root.option_add('*EntryField.errorbackground', 'yellow') 


Pmw.initialise(root, useTkOptionDb=1) 
This construct will be seen in many examples. However, this is a less-frequently used 
option to Pmw. initialise to force the use of the Tk option database. 


Running Example_6_7 displays a screen similar to figure 6.2. Notice how the date and 
Social Security fields havea shaded background to indicate that they contain an invalid 
format. 

Although validation of this kind is provided automatically by the Pmw Entryfield wid- 
get, it has some drawbacks. 


1 There is no indication of the actual validation error. The user is required to determine 
the cause of the error himself. 


2 Data which is valid, when complete, is indicated as being in error as it is being entered 
(the Social Security field in figure 6.2 is a good example). 
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3 Where validation requires complex calculations and access to servers and databases, etc,. 
the processing load can be high. This could be a source of performance problems in cer- 
tain environments. 


To circumvent these and other problems you may use alternative approaches. Of course, 
your application may not use Pmw widgets, so yet another approach may be required. 





No Personally, I prefer not to use the built-in validation in Pmw widgets. If the 

action of formatting the content of the widget requires a redraw, you may 
observe annoying display glitches, particularly if the system is heavily loaded; these may 
distract the user. The following method avoids these problems. 





To avoid validating every keystroke (which is how the Pmw EntryField manages data 
input), we will arrange for validation to be done in the following cases: 
1 When the user moves the mouse pointer out of the current field. 
2 When the focus is moved from the field using the Tas key. 
3 When the ENTER key is pressed. 
Validating this way means that you don’t get false errors as an input string is built up. In 


figure 6.3, for example, entering 192 .311.40.10 would only raise a validation error when the 
field was left or if RETURN was pressed, thereby reducing operator confusion and CPU overhead. 


Invalid IP Addre...EA 


Format: nnn.nnn.nnn.nnn 
-1 < nnn < 256 













Entry Validation 


IP Address: 192.111.40.10 


Card - Port: Jo1-32 
Logical Name: |cP-ser ial-mux 





Format: nnn-nnn 
O< nnn < 101 


Figure 6.3 Data verification: 
error dialogs 


Example_6_8.py 


import string 
from Tkinter import * 
from validation import * 
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class EntryValidation: 


def __init__(self, master): 
self._ignoreEvent = 0 
self._ipAddrvV = self._crdprtV = self._lnameV = '' 





frame = Frame(master) 
Label(frame, text=' ') .grid(row=0, column=0,sticky=W) 
Label(frame, text=' ') .grid(row=0, column=3,sticky=W) 


self._ipaddr = self.createField(frame, width=15, row=0, col=2, 
label='IP Address:', valid=self.validate, 
enter=self.activate) 

self._crdprt = self.createField(frame, width=8, row=1, col=2, 


label='Card - Port:', valid=self.validate, 
enter=self.activate) 

self._lname = self.createField(frame, width=20, row=2, col=2, 
label='Logical Name:', valid=self.validate, 


enter=self.activate) 


self._wDict = {self._ipaddr: ('_ipAddrvV', validIP), 
self._crdprt: ('_crdprtV', validCP), 
self._lname: ('_InameV', validLName) } 


frame.pack(side=TOP, padx=15, pady=15) 


def createField(self, master, label='', text='', width=1, 
valid=None, enter=None, row=0, col=0): 
Label (master, text=label).grid(row=row, column=col-1, sticky=W) 
id = Entry(master, text=text, width=width, takefocus=1) 
id.bind('<Any-Leave>', valid) 
id.bind('<FocusOut>', valid) 
id.bind('<Return>', enter) 
id.grid(row=row, column=col, sticky=W) 
return id 





def activate(self, event): 
print '<Return>: value is', event.widget.get() 


def validate(self, event): 


if self._ignoreEvent: 
self._ignoreEvent = 0 


else: 








currentValue = event.widget.get() 
if currentValue: 
var, validator = self._wDict[event.widget] 
nValue, replace, valid = validator (currentValue) |e 


if replace: 
self._ignoreEvent = 1 
setattr(self, var, nValue) 
event .widget.delete(0, END) 
event .widget.insert(0, nValue) 
if not valid: 
self._ignoreEvent = 1 
event .widget.focus_set() 


root = Tk() 
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root.option_add('*Font', 'Verdana 10 bold') 
root.option_add('*Entry.Font', ‘Courier 10') 
root.title('Entry Validation') 


top = EntryValidation (root) 
quit = Button(root, text='Quit', command=root.destroy) 
quit.pack(side = 'bottom') 


root.mainloop() 





Code comments 


The grid geometry manager sometimes needs a little help to lay out a screen. We use an 
empty first and last column in this example: 
Label (frame, text=' ') .grid(row=0, column=0,sticky=W) 
Label(frame, text=' ') .grid(row=0, column=3,sticky=W) 
You cannot use the Grid manager’s minsize option if the column (or row) is empty; 
you have to use the technique shown here. As an alternative, you can pack the gridded widget 
inside a Frame and use padding to add space at the sides. 


Since we are using native Tkinter widgets, we have to create a Label and Entry widget for 
each row of the form and place them in the appropriate columns. We use the createField 
method to do this. 


We create a dictionary to define a variable used to store the contents of each widget. 


self._wDict = {self._ipaddr: ('_ipAddrV', validIP), 
self._crdprt: ('_crdprtV', validCP), 
self._lname: ('_lnameV', validLName) } 


Using the dictionary enables us to use bindings to a single event-handler with multiple 
validators, which simplifies the code. 


The bindings for validation are when the cursor leaves the widget and when focus is lost (tab- 
bing out of the field). We also bind the activate function called when the ENTER key is 
pressed. 
id.bind('<Any-Leave>', valid) 
id.bind('<FocusOut>', valid) 
id.bind('<Return>', enter) 
One of the complications of using this type of validation scheme is that whenever a field loses 
focus, its validator is called—including when we return to a field to allow the user to correct 
an error. We provide a mechanism to ignore one event: 
if self._ignoreEvent: 
self._ignoreEvent = 0 
We get the variable and validator for the widget creating the event: 
var, validator = self._wDict[event.widget] 
nValue, replace, valid = validator (currentValue) 
and call the validator to check the widget’s contents—possibly editing the content, as 
appropriate. 
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Finally, we react to the result of validation, setting the widget’s content. In the case of a vali- 
dation error, we reset focus to the widget. Here we set the flag to ignore the resulting focus 
event: 


self._ignoreEvent = 1 


6.8.3 Formatted (smart) widgets 


Several data-entry formats benefit from widgets that format data as it is entered. Some exam- 
ples include dates, times, telephone numbers, Social Security numbers and Internet (IP) 
addresses. Making this work may reintroduce some of the issues that were solved by the previ- 
ous example, since the ideal behavior of the widget is to update the format continuously as 
opposed to the alternate scheme of reformatting the field after it has been entered. This intro- 
duces even more problems. Take entering a phone number, for example. Several number 
groupings are typical: 


1 1-(401) 111-2222 Full number with area code 


2 1-401-111-2222 Full number separated with dashes 
3 401-111-2222 Area code and number without / 
4 111-2222 Local number 

5 017596-475222 International (United Kingdom) 


6 3-1111-2222 International (Japan) 


With so many combinations, it is important that the user is shown the format of the tele- 
phone number, or other data, in the label for the widget. If your application has requirements 
to accommodate a range of conflicting formats, it may be better to format the string after it 
has been entered completely or else leave the formatting to the user. For date and time fields, 
you might want to use Pmw widgets, which help the user get the input in the correct format. 

For other formats, you are going to have to write code. This example demonstrates how 
to format phone numbers and Social Security numbers. 


Example_6_ 9.py 


import string 
from Tkinter import * 





class EntryFormatting: 
def __init__(self, master): 
frame = Frame(master) 
Label(frame, text=' ') .grid(row=0, column=0,sticky=W) 
Label (frame, text=' ') .grid(row=0, column=3,sticky=W) 


self._ipaddr = self.createField(frame, width=16, row=0, col=2, 


label='Phone Number: \n(nnn)-nnn-nnn', 
format=self.fmtPhone, enter=self.activate) © 

self._crdprt = self.createField(frame, width=11, row=1, col=2, 
label='SSN#:', format=self.fmtSSN, 
enter=self.activate) 

frame.pack(side=TOP, padx=15, pady=15) 
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def createField(self, master, label='', text='', width=1, 
format=None, enter=None, row=0, col=0): 
Label (master, text=label).grid(row=row, column=col-1, 
padx=15, sticky=W) 

id = Entry(master, text=text, width=width, takefocus=1) 
id.bind('<KeyRelease>', format) 0 
id.bind('<Return>', enter) 
id.grid(row=row, column=col, pady=10, sticky=W) 
return id 


def activate(self, event): 
print '<Return>: value is', event.widget.get() 


def fmtPhone(self, event): 
current = event.widget.get() 


if len(current) == 1: (3) 
current = '1-(%s' % current 

elif len (current) == 6: 
current = '%s)-' % current 

elif len (current) == 11: 
current = '%s-' % current 


event .widget.delete(0, END) 
event .widget.insert (0, current) 


def fmtSSN(self, event): 
current = event.widget.get() 


if len(current) in [3, 6]: 
current = '%s-' % current 
event .widget.delete(0, END) 


event .widget.insert(0, current) 


root = Tk() 
root.title('Entry Formatting') 


top = EntryFormatting (root) 
quit = Button(root, text='Quit', command=root.destroy) 
quit.pack(side = 'bottom') 


root.mainloop() 





Code comments 


The createField method provides a wrapper to bind a formatting function that runs when- 
ever the user presses a key. 


This is the binding that initiates the formatting. 


The fmtPhone method has to count the digits entered into the field to supply the additional 
separators. 


Similarly, £mt SSN inserts hyphens at the appropriate positions. 


If you run Example_6_9.py, you will see output similar to figure 6.4. 
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SUMMARY 


Entry Formatting BE 
ene oe l- (401) -555-1212 
SSN#: [0109-10-0101 


Quit 


Figure 6.4 Simple formatted widgets 





Summary 


The material contained in this chapter is important to a GUI programmer. Almost all GUIs 
are event-driven and appropriate responses to what can be a deluge of events can be important 
for performance-sensitive applications. 

The second half of the chapter introduced data input validation. This is also an important 
topic, since failure to identify values that are inappropriate can be infuriating to a user, espe- 
cially if the user has to retype information into a data-entry screen. 
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Usin g classes, co mposites 
and special widgets 


7.1 Creating a Light Emitting Diode class 120 
7.2. Building a class library 129 
7.3 Summary 139 


The Object-Oriented Programming (OOP) capabilities of Python position the language as 
an ideal platform for developing prototypes and, in most cases, complete applications. One 
problem of OOP is that there is much argument over the methodologies (Object-Oriented 
Analysis and Design—OOAD) which lead to OOP, so many developers simply avoid OOP 
altogether and stay with structured programming (or unstructured programming in some 
case). There is nothing really magical about OOP; for really simple problems, it might not 
be worth the effort. However, in general, OOP in Python is an effective approach to devel- 
oping applications. In this chapter, we are making an assumption that the reader is conver- 
sant with OOP in C++, Java or Python, so the basic concepts should be understood. For an 
extended discussion of this subject, Harms’ & McDonalds Quick Python or Lutz and 
Ascher’s Learning Python. 


Creating a Light Emitting Diode class 


The following example introduces an LED class to define Light Emitting Diode objects. 
These objects have status attributes of on, off, warn and alarm (corresponding to typical net- 
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work management alarm levels) along with the blink on/off state, which may be selected at 
instantiation. The LED class also defines the methods to set the status and blink state at run- 
time. Figure 7.1 demonstrates the wide range of LED formats that can be generated from this 
simple class. 





LED Example - Stage 1 





Figure 7.1 LED example 





Example_7_1.py 


from Tkinter import * 


SQUARE =1 
ROUND = 
ARROW = 


w N 


POINT_DOWN = 
POINT_UP = 
POINT_RIGHT = 


| Define constants 
POINT_LEFT = 


WNRO 


STATUS_OFF = 
STATUS_ON = 
STATUS_WARN = 
STATUS_ALARM = 
STATUS_SET = 





O PWN PR 


class StructClass: 


pass 
Color = StructClass() 

Color. PANEL = "#545454 ' 
Color.OFF = '#656565' 
Color.ON = '#00FF33' 
Color . WARN = '#ffcc00' 
Color.ALARM = '#ff4422' 
class LED: 


def __ init__(self, master=None, width=25, height=25, 
appearance=FLAT, 
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status=STATUS_ON, bd=1, 
bg=None, 

shape=SQUARE, outline="", 
blink=0, blinkrate=1, 
orient=POINT_UP, 
takefocus=0) : 


# Preserve attributes 


self.master = master 
self.shape = shape 
self.onColor = Color.ON 
self.offColor = Color.OFF 
self.alarmColor = Color.ALARM 
self.warningColor = Color.WARN 
self.specialColor = '#00ffdd' 
self.status = status 
self.blink = blink 
self.blinkrate = int(blinkrate) 
self.on =0 
self.onState = None 
if not bg: 

bg = Color. PANEL 


## Base frame to contain light 


self. 


basesize 
center 
if self.shape 


d= 


elif 


else: 
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frame=Frame(master, relief=appearance, 
takefocus=takefocus) 

= width 

int (basesize/2) 

SQUARE: 

self.canvas=Canvas(self.frame, height=height, width=width, 

bg=bg, bd=0, highlightthickness=0) 
self.light=self.canvas.create_rectangle(0, 0, width, height, 
fill=Color.ON) 


bg=bg, bd=bd, 


self.shape ROUND: 

r int ( (basesize-2)/2) 

self.canvas=Canvas (self.frame, 
highlightthickness=0, bg=bg, 


width=width, height=width, 
bd=0) 
if bd > 0: 
self .border=self.canvas.create_oval(center-r, 
center+r, center+r) 


center-r, 


r 


= r - bd 
self.light=self.canvas.create_oval(center-r-1, center-r-1, 
center+r, center+r, fill=Color.ON, 
outline=outline) 
# Default is an ARROW 
self.canvas=Canvas(self.frame, 


highlightthickness=0, bg=bg, 


width=width, height=width, 
bd=0) 

d 

d 


x 
Y 


if orient == POINT_DOWN: 0 
self.light=self.canvas.create_polygon(x-d,y-d, x,y+d, 
x+d,y-d, x-d,y-d, outline=outline) 
elif orient POINT_UP: 
self.light=self.canvas.create_polygon(x,y-d, x-d,y+d, 
x+d,y+d, x,y-d, outline=outline) 


CHAPTER 7 CLASSES, COMPOSITES & SPECIAL WIDGETS 











elif orient == POINT_RIGHT: 


self.light=self.canvas.create_polygon(x-d,y-d, xt+d,y, 
x-d,y+d, x-d,y-d, outline=outline) 


elif orient == POINT_LEFT: 





self.light=self.canvas.create_polygon(x-d,y, x+d,y+d, 


x+d,y-d, x-d,y, 


self.canvas.pack(side=TOP, f£i11=X, expand=NO) 


self .update() 


def turnon(self): O 
self.status = STATUS_ON 
if not self.blink: self.update() 
def turnoff(self): 
self.status = STATUS_OFF 
if not self.blink: self.update() 
def alarm(self): 
self.status = STATUS_ALARM 
if not self.blink: self.update() 
def warn(self): 
self.status = STATUS_WARN 
if not self.blink: self.update() 
def set(self, color): 
self.status = STATUS_SET 
self.specialColor = color 
self.update() 
def blinkon(self): 
if not self.blink: 
self.blink ERT 
self.onState = self.status 
self.update() 
def blinkoff (self): 
if self.blink: 
self.blink = 0 
self.status self.onState 
self.onState = None 
self.on = 0 
self .update() 





def blinkstate(self, blinkstate): 
if blinkstate: 
self.blinkon() 
else: 
self .blinkoff() 


def update(self): 
# First do the blink, if set to blink 
if self.blink: 
if self.on: 
if not self.onState: 
self.onState = self.status 
self.status = STATUS_OFF 
self.on = 0 
else: 
if self.onState: 
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self.status = self.onState # Current ON color 
self.on = 1 











if self.status == STATUS_ON: @ 
self.canvas.itemconfig(self.light, fill=self.onColor) 

elif self.status == STATUS_OFF: 
self.canvas.itemconfig(self.light, fill=self.offColor) 

elif self.status == STATUS_WARN: 
self.canvas.itemconfig(self.light, fill=self.warningColor) 

elif self.status == STATUS_SET: 


self.canvas.itemconfig(self.light, fill=self.specialColor) 
else: 





self.canvas.itemconfig(self.light, fill=self.alarmColor) 
self.canvas.update_idletasks () 
if self.blink: 

self.frame.after(self.blinkrate * 1000, self.update) 


if _name__ == '_main_': 
class TestLEDs (Frame) : 
def __ init__(self, parent=None) : 
# List of Colors and Blink On/Off 
states = [(STATUS_OFF, 0), 
(STATUS_ON, 0), 
(STATUS_WARN, 0), 
(STATUS_ALARM, 0), 
(STATUS_SET, 0), 
(STATUS_ON, 1), 
(STATUS_WARN, 1), 
(STATUS_ALARM, 1), 
(STATUS_SET, 1) ] 
# List of LED types to display, 
# with sizes and other attributes 
leds = [(ROUND, 25, 25, FLAT, 0, None, ""), 
(ROUND, 15, 15, RAISED, 1, None, ""), 
(SQUARE, 20, 20, SUNKEN, 1, None, ""), 
(SQUARE, 8, 8, FLAT, 0, None, ""), 
(SQUARE, 8, 8, RAISED, 1, None, ""), 
(SQUARE, 16, 8, FLAT, 1, None, ""), 
( 
( 
( 








ARROW, 14, 14, RIDGE, 1, POINT_UP, ""), 
ARROW, 14, 14, RIDGE, 0, POINT_RIGHT, ""), 
ARROW, 14, 14, FLAT, 0, POINT_DOWN, "white") ] 





Frame.__ init__(self) # Do superclass init 
self.pack() 
self.master.title('LED Example - Stage 1') 





# Iterate for each type of LED 
for shape, w, h, app, bd, orient, outline in leds: 
frame = Frame(self, bg=Color.PANEL) 
frame.pack(anchor=N, expand=YES, f1i11=X) 
# Iterate for selected states 
for state, blink in states: 
LED(frame, shape=shape, status=state, 
width=w, height=h, appearance=app, 
orient=orient, blink=blink, bd=bd, 
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outline=outline) .frame.pack(side=LEFT, 
expand=YES, padx=1, pady=1) 





TestLEDs() .mainloop() 





Code comments 
We have some simple drawing constructs to draw a triangular area on the canvas. 


The LED widget has a number of methods to change the appearance of the display, show sev- 
eral colors and turn blink on and off. 
The selected state of the LED is updated: 


if self.status == STATUS_ON: 
self.canvas.itemconfig(self.light, fill=self.onColor) 


We always flush the event queue to ensure that the widget is drawn with the current appearance. 





Note Throughout this book I will encourage you to find ways to reduce the amount 

of code that you have to write. This does not mean that I am encouraging you 
to write obfuscated code, but there is a degree of elegance in well-constructed Python. 
The TestLEDs class in Example_7_1.py is a good example of code that illustrates Python 
economy. Here I intended to create a large number of LEDs, so I constructed two lists: 
one to contain the various statuses that I want to show and another to contain the LED 
shapes and attributes that I want to create. Put inside two nested loops, we create the 
LEDs with ease. 

This technique of looping to generate multiple instances of objects will be 
exploited again in other examples. You can also expect to see other rather elegant ways of 
creating objects within loops, but more of that later. 





Example_7_1.py produces the screen shown in figure 7.1. Although this might not seem 
to be very useful at this point, it illustrates the ability of Tkinter to produce some output that 
might be useful in an application. 

Unfortunately, it is not possible to see the LEDs flashing on a printed page, so you will 
have to take my word that the four columns on the right flash on and off (you can obtain the 
examples online to see the example in action). 





see) a |X 


Figure 7.2 LED example (shorter code) 
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7.1.1 Let’s try that again 


One thing that most Python programmers quickly discover is that whenever they take a look 
at a piece of code they wrote some time before, it always seems possible to rewrite it in fewer 
lines of code. In addition, having written a segment of code, it is often possible to reuse that 
code in later segments. 

To demonstrate the ability to reduce the amount of code required to support our exam- 
ple, let’s take a look at how we can improve the code in it. First, we'll remove the constants 
that we defined at the start of the program and save the code in Common_7_1.py; I’m sure 
that we'll be using these constants again in later examples. 


Common_7_1.py 


SQUARE =. Ay 
ROUND = 2 
Color . WARN = '#ffcc00' 
Color .ALARM = '#ff4422' 


Now, we have an excellent opportunity to make the LED methods mixins, since we can 
readily reuse the basic methods of the LED class to construct other widgets. 


GUICommon_7_1.py 


from Common_7_1 import * 


class GUICommon: 
def turnon(self): 
self.status = STATUS_ON 
if not self.blink: self.update() 


def turnoff(self): 
self.status = STATUS_OFF 
if not self.blink: self.update() 


def alarm(self): 
self.status = STATUS_ALARM 
if not self.blink: self.update() 


def warn(self): 
self.status = STATUS_WARN 
if not self.blink: self.update() 











def set(self, color): 
self.status = STATUS_SET 
self.specialColor = color 
self.update() 











def blinkon(self): 
if not self.blink: 
self.blink => 
self.onState self.status 
self.update() 


I 
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def blinkoff(self): 
if self.blink: 
self. blink = 0 
self.status = self.onState 
self.onState = None 
self.on=0 
self.update() 
def blinkstate (self, blinkstate): 
if blinkstate: 
self.blinkon() 
else: 
self. blinkoff() 


def update(self): 
raise NotImplemented 





Error 


# The following define drawing vertices for various 


# graphical elements 














ARROW_HEAD_VERTICES = [ 
[ “see fared, 78, yd, “eed, yd xed “ye; 8 
Ezi iyea's. ‘a0, byte; tdh bysds TG 'y-d'], 
['x-d', 'y-d', ‘'xtd', 'y', 'x-d', 'ytd', 'x-d', 'y-d'], 
['x-d', 'y', 'x+d', ‘'y+d', 'x+d', 'y-d', 'x-d', 'y' J] 





Code comments 


@ Note that although we have added methods such as turnon and blinkoff, we have defined 
an update method that raises a Not ImplementedError. Since every widget will use very 
different display methods, this serves as a reminder to the developer that he is responsible for 


providing a method to override the base class. 


@ The previous code used a four-case if-elif- 


else statement to process the arrow direction. 


I like to remove these whenever possible, so we'll take a different approach to constructing the 
code. Instead of breaking out the individual vertices for the arrow graphic, we are going to 


store them in yet another list, ARROW_HEAD_V1 


Example_7_2.py 


from Tkinter import * 
from Common_7_1 import * 
from GUICommon_7_1 import * 


class LED(GUICommon) : 
def _ init_ (self, 





master=None, 


width=25, 


ERTICES, for later use. 





o 


height=25, 


appearance=FLAT, 
status=STATUS_ON, bd=1, 


bg=None, 
shape=SQUAR 
blink=0, 





E 
G, 


outline='', 
blinkrate=1, 


orient=POINT_UP, 


takefocus=0): 
# Preserve attributes 
self.master master 
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self.shape = shape 


self.Colors = [None, Color.OFF, Color.ON, 
Color.WARN, Color.ALARM, ‘#00ffdd’] »® 
self.status = status 
self.blink = blink 
self.blinkrate = int(blinkrate) 
self.on =0 
self.onState = None 
if not bg: 


bg = Color.PANEL 


## Base frame to contain light 
self.frame=Frame(master, relief=appearance, bg=bg, bd=bd, 
takefocus=takefocus) 


basesize = width 
d = center = int (basesize/2) 


if self.shape == SQUARE: 
self.canvas=Canvas(self.frame, height=height, width=width, 
bg=bg, bd=0, highlightthickness=0) 


self.light=self.canvas.create_rectangle(0, 0, width, height, 
f£ill=Color.ON) 
elif self.shape == ROUND: 
r = int((basesize-2) /2) 
self.canvas=Canvas(self.frame, width=width, height=width, 
highlightthickness=0, bg=bg, bd=0) 
if bd > 0: 
self .border=self.canvas.create_oval(center-r, center-r, 
center+r, center+r) 
r= r - bd 
self.light=self.canvas.create_oval(center-r-1, center-r-1, 
center+r, center+r, 
fill=Color.ON, 
outline=outline) 
else: # Default is an ARROW 
self.canvas=Canvas(self.frame, width=width, height=width, 
highlightthickness=0, bg=bg, bd=0) 
xed 
y=d © 


VL = ARROW_HEAD_VERTICES[orient] # Get the vertices for the arrow 
self.light=self.canvas.create_polygon(eval(VL[0]), 














eval (VL[1]), eval(VL[2]), eval(VL[3]), 
eval (VL[4]), eval(VL[5]), eval(VL[6]), 
eval (VL[7]), outline = outline) 





self.canvas.pack(side=TOP, fil1=X, expand=NO) 
self.update() 


def update(self): 
# First do the blink, if set to blink 
if self.blink: 
if self.on: 
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7.1.2 


7.2 


if not self.onState: 
self.onState = self.status 
self.status = STATUS_OFF 
self.on = 0 
else: 
if self.onState: 
self.status = self.onState # Current ON color 
self.on = 1 


# Set color for current status 
self.canvas.itemconfig(self.light, fill=self.Colors[self.status] ) 


self.canvas.update_idletasks () 


if self.blink: 
self.frame.after(self.blinkrate * 1000, self.update) 





Code comments 
First, we import the newly-created constants file and the GUI mixins. 


We inherit from the GUrCommon mixin. This mixin does not have a constructor so we do not 
need to call it. 


We build a list of colors, which act as an enumeration when we key by current status. 


We extract the appropriate list of x/y coordinate data and eval each value to calculate the off- 
set based on the current location. 


What has changed? 


Actually, we have not changed very much. We have removed some common code and created 
a mixin class to allow us to create a superclass to contain some of the reusable code. To elimi- 
nate at least one of the if-elif-else constructs we have made color attributes for the class 
into a list. The ugly code to draw arrowheads has been replaced by a list reference to the 
arrowhead vertices. Similarly, the references to statuses have been converted to a reference to a 
list. Finally, we've changed the appearance of some of the LEDs by changing sizes and out- 
lines so that you know that we have not just copied figure 7.1! 

If Example_7_2.py is run, we'll observe a screen similar to the one generated by the pre- 
vious example (figure 7.2). I don’t expect you to see any change in the execution of the exam- 
ple, but the Python code is somewhat more compact. 


Building a class library 


Now that we have seen the concept of mixin classes and subclassing at work, we can start to 
build our class library of useful objects for our GUIs. There is often a need to create a series of 
coordinated colors in our displays, so let’s create a routine to create a range of coordinated 
shades from a base color. 

First, we have to extend our GUICommon class to add some color transformation methods. 
Here are the mixin methods that we will add to GUICommon_7_l.py to create 
GUICommon_7_2.py: 
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GUICommon_7_2.py (modifications only) 





# This routine modifies an RGB color (returned by winfo_rgb), 
# applies a factor, maps -1 < Color < 255, and returns a new RGB string 
def transform(self, rgb, factor): 
retval = "#" 
for v in [rgb[0], rgb[1], rgb[2]]: 
v = (v*factor) /256 
Le ay 2552 47 = 255) 
if v < 0: v=0 
retval = "%s%02x" % (retval, v) 
return retval 


# This routine factors dark, very dark, light, and very light colors 
# from the base color using transform 
def set_colors(self): 


rgb = self.winfo_rgb(self.base) o 
self.dbase = self.transform(rgb, 0.8) 
self.vdbase = self.transform(rgb, 0.7) 
self.lbase = self.transform(rgb, 1.1) 
self.vlbase = self.transform(rgb, 1.3) 





Code comments 


@ We calculate color variations derived from the base color. winfo_rgb returns a tuple for the 
RGB values. 


@ We set arbitrary values for each of the color transformations. 


The following example illustrates the use of these routines: 


Example_7_3.py 


from Tkinter import * 
from GUICommon_7_2 import * 


import string 


class TestColors(Frame, GUICommon) : 
def __init__(self, parent=None) : 


Frame.__init__(self) @ Init base class 
self.base = "#848484" @ Set base color 
self.pack() 

self.set_colors() @ Spread colors 


self .make_widgets () 


def make_widgets(self): 
for tag in ['VDBase', 'DBase', 'Base', 'LBase', 'VLBase']: 
Button(self, text=tag, bg=getattr(self, ‘%s'% string. lower(tag)), 
fg='white', command=self.quit) .pack(side=LEFT) 





if _ name == '_main_': 
TestColors().mainloop() 


Running Example_7_3.py displays the screen shown in figure 7.3: 
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7.2.1 Adding a hex nut to our class library 





Figure 7.3 Transforming colors 


Now let’s make use of the color transformations to add some visual effects to a drawn object. 
In this example we are going to create hex nuts. As you'll see later, these simple objects can be 
used in many different ways. 

We will begin by extending some of the definitions in Common_7_1.py, which will be 
saved as Common_7_2.py: 


Common_7_2.py 


NUT_FLAT = 0 
NUT_POINT = 
Color .BRONZE = ‘#7e5b41’ 
Color .CHROME = ‘#c5c5b8’ 
Color.BRASS = ‘#cdb800’ 


Here is the code for our HexNut class. This example is a little more complex and has options 
for instantiating a variety of nuts. The test routine illustrates some of the possible variations. 
Running this code displays the window shown in figure 7.4. 








Figure 7.4 Basic nuts 


Example_7_4.py 


from Tkinter import * 
from GUICommon_7_2 import * 
from Common_7_2 import * 
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class HexNut (GUICommon) : 
def __init__(self, master, frame=1, mount=1, outside=70, inset=8, 
bg=Color.PANEL, nutbase=Color.BRONZE, 
top=NUT_FLAT, takefocus=0, x=-1, y=-1): 
points = [ '%d-r2,%d+r,%d+r2,%d+r, sd+r+2,%d,%d+r2,%d-r,\ 
%d-r12,%d-r, 3d-r-2,%d,%d-r2,%d+r', 
'Sd,%d-r-2,%d+r, d-r2, sd+r, $d+r2,%d,Sd+r+2, \ 
Sd-r, Sd+r2,sd-r,%d-r2,%d,%d-r-2' ] 
self.base = nutbase 
self.status = STATUS_OFF 
self.blink = 0 
self.set_colors () 
basesize = outside+4 
if frame: 
self.frame = Frame(master, relief="flat", bg=bg, bd=0, 
highlightthickness=0, 
takefocus=takefocus) 
self.frame.pack (expand=0) 
self.canv=Canvas(self.frame, width=basesize, bg=bg, 
bd=0, height=basesize, 
highlightthickness=0) 





else: 
self.canv = master # it was passed in... 
center = basesize/2 
Lf eo Os 
centerx 
centery 
else: 
centerx = centery = center 
r = outside/2 
## First, draw the mount, if needed 
if mount: 
self .mount=self.canv.create_oval(centerx-r, centery-r, 
centerx+r, centeryt+r, 
fill=self.dbase, 
outline=self.vdbase) 


x 
yi 


I 


## Next, draw the hex nut 

r =r - (inset/2) 

r2 = r/2 

pointlist = points[top] % (centerx,centery,centerx,centery, 
centerx,centery,centerx,centery, 
centerx,centery,centerx,centery, 
centerx, centery) 


setattr(self, 'hexnut', self.canv.create_polygon(pointlist, 
outline=self.dbase, fill=self.lbase) ) 


## Now, the inside edge of the threads 

r=r - (inset/2) 

self.canv.create_oval(centerx-r, centery-r, 
centerx+r, centeryt+r, 
fill=self.lbase, outline=self.vdbase) 

## Finally, the background showing through the hole 

r=r-2 

self.canv.create_oval(centerx-r, centery-r, 
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centerx+tr, centery+r, 
fill=bg, outline="") 
self.canv.pack(side="top", fill='x', expand='no') 


class Nut(Frame, HexNut): 
def __init__(self, master, outside=70, inset=8, frame=1, mount=1, 
bg="gray50", nutbase=Color.CHROME, top=NUT_FLAT) : 
Frame.__init__ (self) 
HexNut.__init__(self, master=master, outside=outside, 
inset=inset, frame=frame, mount=mount, 
bg=bg, nutbase=nutbase, top=top) 


class TestNuts(Frame, GUICommon) : 
def __ init__(self, parent=None) : 
Frame.__init__(self) 
self .pack() 
self.make_widgets() 
def make_widgets (self): 
# List of Metals to create 
metals = [Color.BRONZE, Color.CHROME, Color.BRASS] 
# List of nut types to display, 
# with sizes and other attributes 
nuts = [(70, 14, NUT_POINT, 0), (70, 10, NUT_FLAT, EI g 
(40, 8, NUT_POINT, 0), (100,16, NUT_FLAT, 1)] 
# Iterate for each metal type 
for metal in metals: 
mframe = Frame(self, bg="slategray2") 
mframe.pack(anchor=N, expand=YES, £111=X) 
# Iterate for each of the nuts 
for outside, inset, top, mount in nuts: 

Nut (mframe, outside=outside, inset=inset, 
mount=mount, nutbase=metal, 
bg="slategray2", 
top=top) .frame.pack(side=LEFT, 

expand=YES, 
padx=1, pady=1) 








if _ name == '_main_': 
TestNuts() .mainloop() 





Note Another way of handling variable data: In Example 7_2.py, we used a mecha- 

nism to allow us to draw the vertices of the polygon used for the arrowheads. In 
this example we employ another technique which will be used repeatedly in other exam- 
ples. Because of the relative complexity of the polygon used to depict the hex nut and the 
fact that we have to calculate the vertices for both the point and flat forms of the nut, 
we use the setattr function. This allows us to set the value of an attribute of an object 
using a reference to the object and a string representation of the attribute. 





7.2.2 Creating a switch class 


It’s time for something more interesting than LEDs and nuts. Once you get started creating 
classes it really is hard to stop, so now let’s create some switches. Although these could be 
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pretty boring, we can add some pizzazz to any GUI that represents any device which has on/ 
off controls. We are also going to introduce some animation, albeit simple. 





No In subsequent examples, GUICommon.py and Common.py will be edited 
directly, rather than creating new versions each time. 





We need to define two more constants in Common.py because switches point up when on in 
the U.S., but point down when on in the UK (I know that this is an arcane property of 
switches in these countries, but it is important to the locals!): 


MODE_UK = 0 
MODE_US = 1 


Here is the code to draw a toggle switch: 


Example_7_5.py 


from Tkinter import * 
from GUICommon import * 
from Common import * 


from Example_7_4 import HexNut 


class ToggleSwitch(Frame, HexNut) : 
def __init__(self, master, outside=70, inset=8, bg=Color. PANEL, 
nutbase=Color.CHROME, mount=1, frame=1, 
top=NUT_POINT, mode=MODE_US, status=STATUS_ON) : 











Frame.__init__(self) 

HexNut.__init__(self,master=master, outside=outside+40, 
inset=35, frame=frame, mount=mount, call 
bg=bg, nutbase=nutbase, top=top) constructors 

self.status = status for base classes 

self .mode = mode 

self.center = (outside+44) /2 

self.r = (outside/2)-4 


## First Fill in the center 

self.rl=self.canv.create_oval(self.center-self.r, 
self.center-self.r, self.center+self.r, 
self.centert+self.r, fill=self.vdbase, 
outline=self.dbase, width=1) 

self.update() ## The rest is dependent on the on/off state 


def update(self): 


self.canv.delete('lever') ## Remove any previous toggle lever 

direction = POINT_UP 

if (self.mode == MODE_UK and self.status == STATUS_ON) or \ 
(self.mode == MODE_US and self.status == STATUS_OFF): 








direction = POINT_DOWN 

# Now update the status 

if direction == POINT_UP: 0 
## Draw the toggle lever 
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self.pl=self.canvas.create_polygon(self.center-self.r, 
self.center, self.center-self.r-3, 
self.center-(4*self.r), self.center+self.r+3, 
self.center-(4*self.r), self.center+self.r, 
elf.center, fill=self.dbase, 
outline=self.vdbase, tags="lever") 

centerx = self.center 

centery = self.center - (4*self.r) 

r = self.r + 2 

## Draw the end of the lever 

self.r2=self.canv.create_oval(centerx-r, centery-r, 
centerx+r, centeryt+r, fill=self.base, 
outline=self.vdbase, width=1, tags="lever") 

centerx = centerx - 1 

centery = centery - 3 

r=r/3 

## Draw the highlight 

self.r2=self.canv.create_oval(centerx-r, centery-r, 
centerx+tr, centery+r, fill=self.vlbase, 
outline=self.lbase, width=2, tags="lever") 

else: 

## Draw the toggle lever 

self.pl=self.canv.create_polygon(self.center-self.r, 
self.center, self.center-self.r-3, 
self.center+(4*self.r), self.center+self.r+3, 
self.center+(4*self.r), self.center+self.r, 
self.center, fill=self.dbase, 
outline=self.vdbase, tags="lever") 

centerx = self.center 

centery = self.center + (4*self.r) 

r = self.r + 2 

## Draw the end of the lever 

self.r2=self.canv.create_oval(centerx-r, centery-r, 
centerx+r, centeryt+r, fill=self.base, 
outline=self.vdbase, width=1, tags="lever") 

centerx = centerx - 1 

centery = centery - 3 

r=r/ 3 

## Draw the highlight 

self.r2=self.canv.create_oval(centerx-r, centery-r, 
centerx+r, centeryt+r, fill=self.vlbase, 
outline=self.lbase, width=2, tags="lever") 

self.canv.update_idletasks () 


class TestSwitches (Frame, GUICommon) : 
def __ init__(self, parent=None) : 
Frame.__init__(self) 
self .pack() 
self .make_widgets() 


def make_widgets(self): 
# List of metals to create 





metals = (Color.BRONZE, Color.CHROME, Color.BRASS) 
# List of switches to display, with sizes and other attributes 
switches = [(NUT_POINT, 0, STATUS_OFF, MODE_US), 
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(NUT_FLAT,1, STATUS_ON, MODE_US), 
(NUT_FLAT,0O, STATUS_ON, MODE_UK), 
(NUT_POINT, 0, STATUS_OFF, MODE_UKR) ] 
# Iterate for each metal type 
for metal in metals: 
mframe = Frame(self, bg="slategray2") 
mframe.pack(anchor=N, expand=YES, f£111=X) 
# Iterate for each of the switches 
for top, mount, state, mode in switches: 
ToggleSwitch(mframe, 
mount=mount, outside=20, 
nutbase=metal, mode=mode, 
bg="slategray2", top=top, 
status=state) .frame.pack(side=LEFT, 
expand=YES, 
padx=2, pady=6) 




















if _ name == '_main_': 
TestSwitches() .mainloop() 





Code comments 


direction determines if the toggle is up or down. Since this may be changed programmati- 
cally, it provides simple animation in the GUI. 


Running this code displays the window in figure 7.5. 











Figure 7.5 Toggle switches 


Building a MegaWidget 


Now that we have mastered creating objects and subclassing to create new behavior and 
appearance, we can start to create some even more complex widgets, which will result ulti- 
mately in more efficient GUIs, since the code required to generate them will be quite com- 
pact. First, we need to collect all of the class definitions for LED, HexNut, Nut and 
ToggleSwitch in a single class library called Components.py. 

Next, we are going to create a new class, SwitchIndicator, which displays a toggle 
switch with an LED indicator above the switch, showing the on/off state of the switch. Every- 
thing is contained in a single frame that can be placed simply on a larger GUI. Here is the code 
to construct the composite widget: 
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Example_7_6.py 


from Tkinter import * 
from Common import * 
from Components import * 


class SwitchIndicator: 
def __init__(self, master, outside=70, 
metal=Color.CHROME, mount=1, 








self.frame = Frame (master, bg=bg) 
self.frame.pack(anchor=N, expand=YES, 
self.led = LED(self.frame, width=outside, 
status=status, bg=bg, shape= 
outline=metal) 
self.led.frame.pack(side=TOP) 
self.switch = ToggleSwitch(self.frame, 
outside=outside, 
mode=mode, bg=bg, top= 


status=status) 
switch. frame.pack(side=TOP) 
update () 


self. 
self. 


def update(self): 
self.led.update() 
self.switch.update() 


class TestComposite(Frame): 
def __ init__(self, parent=None) : 
Frame.__init__(self) 
self.pack() 
self.make_widgets() 


def make_widgets (self): 
# List of switches to display, 
# with sizes and other attributes 








bg=Color.PANEL, 
frame= 
shape=ROUND, top=NUT_POINT, mode=MODE_US, 


Ly 
status=1): 


£i11=x) 


height=outside, 
shape, 


mount=mount, 
nutbase=metal, 


top, 


MODE_US), 
MODE_UK) , 


STATUS_OFF, MODE_UK) ] 


switches = [(NUT_POINT, 0, STATUS_OFF, MODE_US), 
(NUT_FLAT,1, STATUS_ON, 
(NUT_FLAT,0, STATUS_ON, 
(NUT_POINT, 0, 

frame = Frame(self, bg="gray80") 


frame.pack(anchor=N, expand=YES, f£111=X) 


for top, mount, state, mode in switches: 

SwitchIndicator (frame, 
mount=mount, 
outside=20, 
metal=Color.CHROME, 
mode=mode, 
bg="gray80", 
top=top, 


status=state) .frame.pack(side=LEFT, 
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expand=YES, 
padx=2, 
pady=6) 


if _ name == '_main_': 
TestComposite() .mainloop() 


You can see from this example that the test code is beginning to exceed the size of the code 
needed to construct the widget; this is not an unusual situation when building Python code! If 
you run Example_7_6.py the following switches shown in figure 7.6 are displayed: 





Figure 7.6 Composite 
Switch/Indicator Widgets 





No The two switches on the left are US switches while the two on the right are UK 
switches. American and British readers may be equally confused with this if 
they have never experienced switches on the opposite side of the Atlantic Ocean. 





In the preceding examples we have simplified the code by omitting to save the instances 
of the objects that we have created. This would not be very useful in real-world applications. 
In future examples we will save the instance in the class or a local variable. Changing our code 
to save the instance has a side effect that requires us to separate the instantiation and the call 
to the Packer in our examples. For example, the following code: 


for top, mount, state, mode in switches: 
SwitchIndicator(frame, mount=mount, outside=20, metal=Color.CHROME, 
mode=mode, bg="gray80",top=top, 
status=state) .frame.pack(side=LEFT, 
expand=YES, padx=2, pady=6) 





becomes: 


idx = 0 
for top, mount, state, mode in switches: 


o 


setattr (self, 'swin%d' % idx, None) 

var = getattr(self, 'swintd' % idx) 

var = SwitchIndicator (frame, 
mount=mount, 
outside=20, 
metal=Color.CHROME, 
mode=mode, 
bg="gray80", 
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SUMMARY 


top=top, 
status=state) 
var.frame.pack(side=LEFT, expand=YES, 
padx=2, pady=6) 





idx = idx +1 
This code is not quite so elegant, but it allows access to the methods of the instance: 


self.swin0.turnon() 
self.swin3 .blinkon() 


There will be several examples of using composite widgets and inherited methods in examples 
in later chapters. 


Summary 


In this chapter we have seen how we can build classes to define quite complex GUI objects 
and that these can be instantiated so that they exhibit quite different appearance even though 
the underlying behavior of the objects is quite similar. I have demonstrated the use of mixin 
classes to encapsulate common properties within related classes, and I have given you some 
insight into the way that Python handles multiple-inheritance. 


139 











CHAPTER 8 











Dialogs and forms 


8.1 Dialogs 141 8.5 Browsers 175 

8.2. A standard application 8.6 Wizards 184 
framework 155 8.7 Image maps 191 

8.3. Data dictionaries 165 8.8 Summary 198 


8.4 Notebooks 172 


This chapter presents examples of a wide range of designs for dialogs and forms. If you are 
not in the business of designing and developing forms for data entry, you could possibly 
expend a lot of extra energy. It’s not that this subject is difficult, but as you will see in 
“Designing effective graphics applications” on page 338, small errors in design quickly lead 
to ineffective user interfaces. 

The term dialog is reasonably well understood, but form can be interpreted in several 
ways. In this chapter the term is used to describe any user interface which collects or dis- 
plays information and which may allow modification of the displayed values. The way the 
data is formatted depends very much on the type of information being processed. A dialog 
may be interpreted as a simple form. We will see examples from several application areas; 
the volume of example code may seem a little overwhelming at first, but it is unlikely that 
you would ever need to use all of the example types within a single application—pick and 
choose as appropriate. 

We begin with standard dialogs and typical fill-in-the-blank forms. More examples 
demonstrate ways to produce effective forms without writing a lot of code. The examples will 
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provide you with some readily-usable templates that may be used in your own applications. 
Many of the standard form methods will be used again in examples in later chapters. 

Pmw widgets will be used extensively in the examples since these widgets encapsulate a 
lot of functionality and allow us to construct quite complex interfaces with a relatively small 
amount of code. The use and behavior of these widgets are documented in more detail in 
“Pmw reference: Python megawidgets” on page 542. 


8.1 Dialogs 


Dialogs are really just special cases of forms. In general, dialogs present warning or error mes- 
sages to the user, ask questions or collect a limited number of values from the user (typically 
one value). You could argue that all forms are dialogs, but we don’t need an argument! Nor- 
mally dialogs are modal: they remain displayed until dismissed. Modality can be application- 
wide or system-wide, although you must take care to make sure that system-modal dialogs are 
reserved for situations that must be acknowledged by the user before any other interaction is 


possible. 





Note Exercise care in selecting when to use a modal dialog to get input from the user. 

You'll have many opportunities to use other methods to get input from the user 
and using too many dialogs can be annoying to the user. A typical problem is an applica- 
tion that always asks “Are you sure you want to...” on almost every operation. This can be 
a valuable technique for novice users, but an expert soon finds the dialogs frustrating. It is 
important to provide a means to switch off such dialogs for expert users. 





Tkinter provides a Dialog module, but it has the disadvantage of using X bitmaps for 
error, warning and other icons, and these icons do not look right on Windows or MacOS. The 
tkSimpleDialog module defines askstring, askinteger and askfloat to collect strings, 
integers and floats respectively. The tkMessageBox module defines convenience functions 
such as showinfo, showwarning, showeerror and askyesno. The icons used for tkMes- 
sageBox are architecture-specific, so they look right on all the supported platforms. 


8.1.1 Standard dialogs 


Standard dialogs are simple to use. Several convenience functions are available in 
tkMessageBox, including showerror, showwarning and askretrycancel. The example 
shown here illustrates the use of just one form of available dialogs (askquest ion). However, 
figure 8.1 shows all of the possible formats both for UNIX and Windows. 


Example_8_1.py 


from Tkinter import * 
from tkMessageBox import askquestion 
import Pmw 


class App: 
def __init__(self, master): 
self.result = Pmw.EntryField(master, entry_width=8, 
value='', 
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label_text='Returned value: ae 
labelpos=W, labelmargin=1) 
self.result.pack(padx=15, pady=15) 


root = Tk() 
question = App(root) 


button = askquestion("Question:", 
"Oh Dear, did somebody\nsay mattress to Mr Lambert?", 
default=NO) 


000 


question.result.setentry (button) 


root.mainloop() 





Code comments 
@ The first two arguments set the title and prompt (since this is a question dialog). 


@ default sets the button with the selected string to be the default action (the action associated 
with pressing the RETURN key). 


© The standard dialogs return the button pressed as a string—for example, ok for the OK but- 
ton, cancel for the CANCEL button. 


For this example, all of the standard dialogs are presented, both for Windows and UNIX 
architectures (the UNIX screens have light backgrounds); the screen corresponding to 
Example_8_1.py is the first screen in figure 8.1. 


8.1.2 Data entry dialogs 


A dialog can be used to request information from the user. Let’s take a quick look at how we 
query the user for data using the tkSimpleDialog module. Unlike many of our examples, 
this one is short and to the point: 


Example_8_2.py 


from Tkinter import * 
from tkSimpleDialog import askinteger 
import Pmw 


class App: 
def __init__(self, master): 
self.result = Pmw.EntryField(master, entry_width=8, 
value='', 
label_text='Returned value: Ay 
labelpos=W, labelmargin=1) 
self.result.pack(padx=15, pady=15) 





root = Tk() 
display = App(root) 


retVal = askinteger("The Larch", o 
"What is the number of The Larch?", 
minvalue=0, maxvalue=50) O 
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Question 


K 


askquestion 


showinfo 


Warning 


showwarning 


showerror 
| Self Defense 
Q 
| askokcancel 
askyesno 
askretrycancel 


Figure 8.1 Standard dialogs 


Question 


® Oh dear, did somebody 
< say mattress to Mr Lambert? 


Yeah, well it’s not easy to pad these 
python files out to 150 lines, you 
know 





OK | 


Warming 


I'm sorry, the five minutes is up 





Ok | 


It’s not a palindrome! 
© The palindrome of Bolton” 
would be ”Notlob”!! 





Self Defense 


? Do you know Llap-Goch? 


Oh, this is futile! 
Try again? 
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display.result.setentry(retVal) 


root.mainloop() 





Code comments 


askinteger can be used with just two arguments: title and prompt. 


In this case, a minimum and maximum value have been added. If the user types a value out- 
side this range, a dialog box is displayed to indicate an error (see figure 8.1). 





Note Avoid popping up dialogs whenever additional information is required from 

the user. If you find that the current form that is displayed frequently requires 
the user to supply additional information, it’s very possible that your original form design 
is inadequate. Reserve popup dialogs for situations which occur infrequently or for near- 
boundary conditions. 





Running Example_8_2.py displays screens similar to those shown in figure 8.2. 


x 


What is the number of The Larch? 


52 
co | 





-ojx 
Returned value: fi 0 













Too large 


x 


What is the number of The Larch? 


10 
co | 





Figure 8.2 tkSimpleDialog: askinteger 


Despite the warning in the note above, if you have just a few fields to collect from the 
user, you can use dialog windows. This is especially true if the application doesn’t require the 
information every time it is run; adding the information to screens in the application adds 
complexity and clutters the screen. Using a dialog saves quite a bit of work, but it may not be 
particularly attractive, especially if you need to have more than two or three entry fields or if 
you need several widget types. However, this example is quite short and to the point. 


Example_8_3.py 


from Tkinter import * 
from tkSimpleDialog import Dialog 
import tkMessageBox 
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import Pmw 


class GetPassword (Dialog) : 
def body(self, master): 
self.title("Enter New Password") 





Label (master, text='Old Password:').grid(row=0, eae 








Label (master, text='New Password:').grid(row=1, sticky=W) 

Label (master, text='Enter New Password Again:').grid(row=2, 
sticky=W) 

self.oldpw = Entry(master, width = 16, show='*') 

self .newpwl Entry(master, width = 16, show='*') 

self.newpw2 = Entry(master, width = 16, show='*') 





self.oldpw.grid(row=0, column=1, sticky=W) 
self .newpwl.grid(row=1, column=1, sticky=W) 
self .newpw2.grid(row=2, column=1, sticky=W) 
return self.oldpw 


def apply (self): 


opw = self.oldpw.get() 

npwl = self.newpwl.get() 

npw2 = self.newpw2.get () Validate 
if not npwl == npw2: 


tkMessageBox.showerror('Bad Password', 
'New Passwords do not match') 
else: 
# This is where we would set the new password... 
pass 


root = Tk() 
dialog = GetPassword (root) 





Code comments 
This example uses the grid geometry manager. The sticky attribute is used to make sure that 
the labels line up at the left of their grid cells (the default is to center the text in the cell). See 
“Grid” on page 86 for more details. 

Label (master, text='Old Password:').grid(row=0, sticky=W) 
Since we are collecting passwords from the user, we do not echo the characters that are typed. 
Instead, we use the show attribute to display an asterisk for each character. 





self.oldpw = Entry(master, width = 16, show='*') 
When the user clicks the OK button, the apply callback gets the current data from the wid- 
gets. In a full implementation, the original password would be checked first. In our case we're 
just checking that the user typed the same new password twice and if the passwords do not 
match we pop up an error dialog, using showerror. 


tkMessageBox.showerror('Bad Password', 
'New Passwords do not match') 


Figure 8.3 illustrates the output of Example_8_3.py. 
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Enter New Password Bad Pass word x| 
& New Passwords do not match 







Old Password: p 


New Password: XXXXXXXXXXXX 


Enter New Password Again: eee] | 


Cancel 


Figure 8.3 A tkSimpleDialog that is used to collect passwords. The error dialog is 
displayed for bad entries. 





38.1.3 Single-shot forms 


If your application has simple data requirements, you may need only simple forms. Many user 
interfaces implement a simple model: 


1 Display some fields, maybe with default values. 
2 Allow the user to fill out or modify the fields. 

3 Collect the values from the screen. 

4 Do something with the data. 

5 


Display the results obtained with the values collected. 


If you think about the applications you’re familiar with, you'll see that many use pretty 
simple, repetitive patterns. As a result, building forms has often been viewed as a rather tedious 
part of developing GUIs; I hope that I can make the task a little more interesting. 

There zs a problem in designing screens for applications that do not need many separate 
screens; developers tend to write a lot more code than they need to satisfy the needs of the 
application. In fact, code that supports forms often consumes more lines of code than we might 
prefer. Later, we will look at some techniques to reduce the amount of code that has to be writ- 
ten, but for now let’s write the code in full. 

This example collects basic information about a user and displays some of it. The example 
uses Pmw widgets and is a little bit longer than it needs to be, so that we can cover the basic 
framework now; we will leave those components out in subsequent examples. 


Example_8_4.py 


from Tkinter import * 
import Pmw 
import string 


class Shell: 


def __init__(self, title=''): 
self.root = Tk() as 


Pmw.initialise(self.root) 
self.root.title(title) 


146 CHAPTER 8 DIALOGS AND FORMS 











DIALOGS 


def doBaseForm(self, master): 
# Create the Balloon. 
self.balloon = Pmw.Balloon(master) 


self.menuBar = Pmw.MenuBar(master, hull_borderwidth=1, 
hull_relief = RAISED, 
hotkeys=1, balloon = self.balloon) 
self .menuBar.pack (£i111=xX) 





self.menuBar.addmenu('File', 'Exit') 
self.menuBar.addmenuitem('File', 'command', 
'Exit the application', 
label='Exit', command=self.exit) 
self.menuBar.addmenu('View', 'View status') 
self.menuBar.addmenuitem('View', 'command', 
"Get user status', 
label='Get status', 
command=self.getStatus) 


self.menuBar.addmenu('Help', ‘About Example 8-4', side=RIGHT) 
self.menuBar.addmenuitem('Help', 'command', 
‘Get information on application', 
label='About...', command=self.help) 


self.dataFrame = Frame(master) 
self.dataFrame.pack(fill=BOTH, expand=1) 


self.infoFrame = Frame(self.root,bd=1, relief='groove') 
self.infoFrame.pack(fill=BOTH, expand=1, padx = 10) 





self.statusBar = Pmw.MessageBar(master, entry_width = 40, 


entry_relief='groove', 

labelpos = W, 

label_text = '') 
self.statusBar.pack(fill = X, padx = 10, pady = 10) 


# Add balloon text to statusBar 


self.balloon.configure(statuscommand = self.statusBar.helpmessage) 


# Create about dialog. 
Pmw.aboutversion('8.1') 
Pmw.aboutcopyright ('Copyright My Company 1999’ 
‘\nAll rights reserved' ) 

Pmw.aboutcontact ( 

'For information about this application contact: \n' 

' My Help Desk\n' 

' Phone: 800 555-1212\n' 

' email: help@my.company.com' 

) 
self.about = Pmw.AboutDialog(master, 

applicationname = 'Example 8-4') 

self.about.withdraw() 


def exit(self): 
import sys 
sys.exit (0) 


+ 
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Code comments 


The constructor initializes both Tk and Pmw: 


self.root = Tk() 
Pmw.initialise(self.root) 


Note that Pmw. initialise is not a typo; Pmw comes from Australia! 


We create an instance of the Pmw.Balloon to implement Balloon Help. Naturally, this bit 
could have been left out, but it is easy to implement, so we might as well include it. 
self.balloon = Pmw.Balloon(master) 


Actions are bound later. 


The next few points illustrate how to construct a simple menu using Pmw components. First 
we create the MenuBar, associating the balloon and defining hotkey as true (this creates 
mnemonics for menu selections). 


self.menuBar = Pmw.MenuBar(master, hull_borderwidth=1, 
hull_relief = RAISED, 
hotkeys=1, balloon = self.balloon) 
self .menuBar.pack (£i11=X) 





It is important to pack each form component in the order that they are to be 

Nete P P P y: 
displayed—having a menu at the bottom of a form might be considered a little 
strange! 





The File menu button is created with an addmenu call: 


self.menuBar.addmenu('File', 'Exit') 


The second argument to addmenu is the balloon help to be displayed for the menu but- 
ton. We then add an item to the button using addmenuitem: 
self.menuBar.addmenuitem('File', 'command', 
'Exit the application', 
label='Exit', command=self.exit) 
addmenuitem creates an entry within the specified menu. The third argument is the 


help to be displayed. 


We create a Frame to contain the data-entry widgets and a second frame to contain some dis- 
play widgets: 
self.dataFrame = Frame (master) 
self.dataFrame.pack(fill=BOTH, expand=1) 
At the bottom of the form, we create a statusBar to display help messages and other infor- 
mation: 
self.statusBar = Pmw.MessageBar (master, entry_width = 40, 
entry_relief=GROOVE 
labelpos = W, 
label_text = '') 
self.statusBar.pack(fill = X, padx = 10, pady = 10) 





We bind the balloon’s statuscommand to the MessageBar widget: 


self.balloon.configure(statuscommand = self.statusBar.helpmessage) 
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@ Wecreate an About... dialog for the application. This is definitely something we could have 
left out, but now that you have seen it done once, I won't need to cover it again. First, we 
define the data to be displayed by the dialog: 

Pmw.aboutversion('8.1') 
Pmw.aboutcopyright ('Copyright My Company 1999’ 
‘\nAll rights reserved' ) 

Pmw.aboutcontact ( 

'For information about this application contact:\n' + 

' My Help Desk\n' + 

' Phone: 800 555-1212\n' + 

' email: help@my.company.com' ) 

© Then the dialog is created and withdrawn (unmapped) so that it remains invisible until 
required: 





self.about = Pmw.AboutDialog(master, applicationname = 'Example 8-1') 
self .about.withdraw() 


Example_8_4.py (continued) 


def getStatus(self): 
username = self.userName.get () 
cardnumber = self.cardNumber.get () 


self.img = PhotoImage(file='%s.gif' % username) 
self.pictureID['image'] = self.img 


self.userInfo.importfile('%s.txt' % username) 
self.userInfo.configure(label_text = username) 


def help(self): 
self.about.show() 


oob o 


def doDataForm(self): 
self.userName=Pmw.EntryField(self.dataFrame, entry_width=8, 
value='', 
modifiedcommand=self.upd_username, 
label_text='User name:', 
labelpos=W, labelmargin=1) 
self.userName.place(relx=.20, rely=.325, anchor=W) 





self.cardNumber = Pmw.EntryField(self.dataFrame, entry_width=8, 
value='', 
modifiedcommand=self.upd_cardnumber, 
label_text='Card number: hey 
labelpos=W, labelmargin=1) 
self.cardNumber.place(relx=.20, rely=.70, anchor=W) 





def doInfoForm(self): 
self .pictureID=Label (self.infoFrame, bd=0) 
self.pictureID.pack(side=LEFT, expand=1) 


self.userInfo = Pmw.ScrolledText (self.infoFrame, 
borderframe=1, 
labelpos=N, 
usehullsize=1, 
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hull_width=270, 

hull_height=100, 

text_padx=10, 

text_pady=10, 

text_wrap=NONE) 
self.userInfo.configure(text_font = ('verdana', 8) ) 
self.userInfo.pack(fill=BOTH, expand=1) 





def upd_username(self): 
upname = string.upper(self.userName.get () ) 
if upname: 
self.userName.setentry (upname) 


def upd_cardnumber (self): 
valid = self.cardNumber.get () 
if valid: 
self.cardNumber.setentry (valid) 


if _ name == '_main_': 
shell=Shell (title='Example 8-4') 
shell.root.geometry("%dx%d" % (400,350) ) 
shell .doBaseForm(shell.root) 
shell .doDataForm() 
shell .doInfoForm() 
shell.root.mainloop() 





Code comments (continued) 


@  getStatus isa placeholder for a more realistic function that can be applied to the collected 
data. First, we use the get methods of the Pmw widgets to obtain the content of the widgets: 
username = self.userName.get () 


cardnumber = self.cardNumber.get () 


@ Using username, we retrieve an image and load it into the label widget we created earlier: 


o 2 


self.img = PhotoImage(file='%s.gif' % username) 
self.pictureID['image'] = self.img 


@ Then we load the contents of a file into the ScrolledText widget and update its title: 


2 


self.userInfo.importfile('%s.txt' % username) 
self.userInfo.configure(label_text = username) 
@ Using the About dialog is simply a matter of binding the widget’s show method to the menu 
item: 
def help(self): 
self.about.show() 





@ The form itself uses two Pmw EntryField widgets to collect data: 


self.userName=Pmw.EntryField(self.dataFrame, entry_width=8, 
value='', 
modifiedcommand=self.upd_username, 
label_text='User name:'‘, 
labelpos=W, labelmargin=1) 

self.userName.place(relx=.20, rely=.325, anchor=W) 
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@ The modifiedcommand in the previous code fragment binds a function to the widget to be 
called whenever the content of the widget changes (a valuechanged callback). This allows us 
to implement one form of validation or, in this case, to change each character to upper case: 

upname = string.upper(self.userName.get() ) 
if upname: 
self.userName.setentry (upname) 


@ Finally, we create the root shell and populate it with the subcomponents of the form: 
shell=Shell(title='Example 8-4') 
shell.root.geometry("%dx%d" % (400,350) ) 
shell .doBaseForm(shell.root) 
shell .doDataForm() 
shell .doInfoForm() 
shell.root.mainloop() 





Note that we delay calling the doBaseFrorm, doDataForm and doInfoForm methods to 
allow us flexibility in exactly how the form is created from the base classes. 


If you run Example_8_4.py, you will see screens similar to the one in figure 8.4. Notice 
how the ScrolledText widget automatically adds scroll bars as necessary. In fact, the overall 
layout changes slightly to accommodate several dimension changes. The title to the 
ScrolledText widget, for example, adds a few pixels to its containing frame; this has a slight 
effect on the layout of the entry fields. This is one reason why user interfaces need to be com- 
pletely tested. 





Note Automatic scroll bars can introduce some bothersome side effects. In figure 8.4, 

the vertical scroll bar was added because the number of lines exceeded the 
height of the widget. The horizontal scroll bar was added because the vertical scroll bar 
used space needed to display the longest line. If] had resized the window about 10 pixels 
wider, the horizontal scroll bar would not have been displayed. 












Example 





File View 


User name: [GuIDq 
Card number: 






View user information 


User name: 


Card number: | 






















Pronunciation: 
In Dutch, the "G" in Guido is a hard G, 
pronounced roughly like the "ch" in 
Scottish "loch". (Listen to the sound 

clip below.) However, if you're Americar 
you may also pronounce it as the Italiar 
"Guido". I'm not too worried about the 
associations with mob assassins that 
some people have :-) 








View user information 











Figure 8.4 Single-shot form 
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8.1.4 Tkinter variables 


The previous example used Pmw widgets to provide setentry and get methods to give 
access to the widget’s content. Tk provides the ability to link the current value of many wid- 
gets (such as text, toggle and other widgets) to an application variable. Tkinter does not 
support this mode, instead it provides a Variable class which may be subclassed to give 
access to the variable, textvariable, value, and other options within the widget. Cur- 
rently, Tkinter supports StringVar, IntVar, DoubleVar and BooleanVar. These objects 
define get and set methods to access the widget. 


Example_8_5.py 


from Tkinter import * 


class Var (Frame): 
def _ init_ (self, master=None) : 
Frame.__init__(self, master) 
self.pack() 


self.field = Entry() 
self.field.pack() 


self.value = StringVar () 
self.value.set ("Jean-Paul Sartre") 
self.field["textvariable"] = self.value 


self.field.bind('<Key-Return>', self.print_value) 


def print_value(self, event): 
print 'Value is "%s"' % self.value.get() (4) 


test = Var() 
test.mainloop() 





Code comments 


@ Remember that you cannot get directly at the Tk widget’s variable; you must create a Tkinter 
variable. Here we create an instance of StringVar. 


@ Set the initial value. 
© Bind the variable to the text variable option in the widget. 


© Extract the current value using the get method of the string variable. 


rn -Of x| 
[Jean-Paul Sartre 


Figure 8.5 Using 
Tkinter variables 


If you run this example, you will see a dialog similar to 
figure 8.5. This is as simple a dialog as you would want to see; 
on the other hand, it really is not very effective, because the only 
way to get anything from the entry field is to press the RETURN 
key, and we do not give the user any information on how to use 
the dialog. Nevertheless, it does illustrate Tkinter variables! 





Pmw provides built-in methods for setting and getting values within widgets, so you do 
not need to use Tkinter variables directly. In addition, validation, valuechanged (modi- 
fied) and selection callbacks are defined as appropriate for the particular widget. 
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Example_8 6.py 


DIALOGS 


from Tkinter import * 
from tkSimpleDialog import Dialog 
import Pmw 


class MixedWidgets (Dialog): 
def body(self, master): 


Label (master, text='Select Case:').grid(row=0, sticky=W) 
Label (master, text='Select Type:').grid(row=1, sticky=W) 
Label (master, text='Enter Value:').grid(row=2, sticky=W) 





self.combol = Pmw.ComboBox(master, 
scrolledlist_items=("Upper", "Lower", "Mixed"), 
entry_width=12, entry_state="disabled", 
selectioncommand = self.ripple) 

self.combol.selectitem("Upper") 

self.combol.component ('entry') .config(bg='gray80') 


600 


self.combo2 = Pmw.ComboBox(master, scrolledlist_items=(), 
entry_width=12, entry_state="disabled") 
self.combo2.component ('entry') .config (background='gray80') 





self.entryl = Entry(master, width = 12) 


self.combol.grid(row=0, column=1, sticky=W) 
self.combo2.grid(row=1, column=1, sticky=W) 
self.entryl.grid(row=2, column=1, sticky=W) 


return self.combol 


def apply(self): 
cl = self.combol.get() 
c2 = self.combo2.get() 
el = self.entryl.get() 
print c1, c2, el 


def ripple(self, value): 


lookup = {'Upper': ("ANIMAL", "VEGETABLE", "MINERAL"), 
'Lower': ("animal", "vegetable", "mineral"), 
'Mixed': ("Animal", "Vegetable", "Mineral")} 

items = lookup[value] 

self.combo2.setlist (items) O 


self.combo2.selectitem(items[0]) 


root = Tk() 
dialog = MixedWidgets (root) 





Code comments 

ComboBoxes are important widgets for data entry and selection. One of their most valuable 
attributes is that they occupy little space, even though they may give the user access to an 
unlimited number of selectable values. 


self.combol = Pmw.ComboBox (master, 
scrolledlist_items=("Upper", "Lower", "Mixed"), 
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In this case, we are just loading three values into the combo’s list. Typically data may be 
either loaded from databases or calculated. 


We do not intend for the values selected in this ComboBox to be editable, so we need to dis- 
able the entry field component of the widget. 
entry_width=12, entry_state="disabled", 
self.combol.component ('entry') .config(bg='gray8s0' ) 
We set the background of the Entry widget to be similar to the background to give the 
user a clear indication that the field is not editable. 


This one is an unusual one. Frequently, fields on a screen are dependent on the values con- 
tained within other fields on the same screen (on other screens in some cases). So, if you 
change the value in the combobox, you ripple the values within other widgets. (Ripple is a 
term that I invented, but it somewhat conveys the effect you can see as the new values ripple 
through the interface.) 


selectioncommand = self.ripple) 





No Careless use of the ripple technique can be dangerous! Using ripple must be 
considered carefully, since it is quite easy to design a system which results in 
constant value modification if several fields are dependent on each other. Some sort of 
control flag is necessary to prevent a continuous loop of select ioncommand callbacks 
consuming CPU cycles. 
See “Tkinter performance” on page 350 for other important factors you should 
consider when designing an application. 





We select default value from the lists or else the entry would be displayed as blank, which 
is probably not appropriate for a non-editable combobox. 
self.combol.selectitem("Upper") 
This is our ripple callback function. The selectioncommand callback returns the value of 
the item selected as an argument. We use this to look up the list to be applied to the second 
combobox: 
def ripple(self, value): 


lookup = {'Upper': ("ANIMAL", "VEGETABLE", "MINERAL") , 
'Lower': ("animal", "vegetable", "mineral"), 
'Mixed': ("Animal", "Vegetable", "Mineral") } 


items = lookup[value] 
The list obtained from the lookup replaces the current list. 


self.combo2.setlist (items) 
self.combo2.selectitem(items[0] ) 


As before, you need to select one of the values in the lists to be displayed in the widget. 


If you run Example_8_6.py, you will see this simple example of rippled widgets. Part of 
the effect can be seen in figure 8.6. 
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Select Case: [Upper xj 


Select Type: | x 


Enter Value: | 


Cancel | 


Select Case: [Lower xj 
Select Type: [animal x 


Enter Value: 






Cancel | 





tk E 


Select Case: [Lower xj 
Select Type: [animal x 
Enter Value: [aardvard Figure 8.6 Handling 


Cancel | dependencies between 


widgets— Ripple 





8.2 A standard application framework 


One of the problems with designing forms is that some features are common to most applica- 
tions. What we need is a standard application framework which can be adapted to each appli- 
cation; this should result in moderate code reuse. Many applications fit the general form 
shown in figure 8.7. In addition, we need the ability to provide busy cursors *, attach balloon 


Title 

Menu Bar 

Data Area 
Control Buttons 
Status Area 


Progress Area 
Figure 8.7 Standard application framework 


help and help messages to fields, supply an about... message and add buttons with appropri- 
ate callbacks. To support these needs, Ill introduce AppShell.py, which is a fairly versatile 
application framework capable of supporting a wide range of interface needs. Naturally, this 
framework cannot be applied to all cases, but it can go a long way to ease the burden of devel- 
oping effective interfaces. 





* A busy cursor is normally displayed whenever an operation takes more than a few hundred millisec- 
onds, it is often displayed as a watch or hourglass. In some cases the application may also inhibit 
button-presses and other events until the operation has completed. 
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Since AppShell is an important feature of several of our examples, we are going to examine 
the source code in detail; additionally, if you are going to use AppShell directly, or adapt it for 
your own needs, you need to understand its facilities and operations. 


AppShell.py 


from Tkinter import * 

import Pmw 

import sys, string 

import ProgressBar @ 


class AppShell (Pmw.MegaWidget) : 
appversion= '1.0' 
appname = 'Generic Application Frame' 
copyright= 'Copyright YYYY Your Company. All Rights Reserved' 2 
contactname= 'Your Name' 
contactphone= '(999) 555-1212' 
contactemail= 'youremail@host.com' 


frameWidth= 450 
frameHeight= 320 
padx = 5 B 
pady =5 
usecommandarea= 0 
balloonhelp= 1 





busyCursor = 'watch' 


def _ init_ (self, **kw): 


optiondefs = ( 
('padx', Ty Pmw.INITOPT) , 
('‘pady', 1, Pmw.INITOPT) , O 
('framewidth', 1, Pmw.INITOPT), 
('frameheight', 1,Pmw.INITOPT), 








('usecommandarea', self.usecommandarea, Pmw.INITOPT) ) 
self.defineoptions(kw, optiondefs) 


self.root = Tk() 
self.initializeTk(self.root) 
Pmw.initialise(self.root) | 9 
self.root.title(self.appname) 
self.root.geometry('%dx%d' % (self.frameWidth, 
self.frameHeight) ) 





# Initialize the base class 
Pmw.MegaWidget.__init__(self, parent=self.root) O 


# Initialize the application 
self.appInit() 


# Create the interface 
self.__createInterface() 


# Create a table to hold the cursors for 
# widgets which get changed when we go busy 
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self.preBusyCursors = None 


# Pack the container and set focus 

# to ourselves 

self._hull.pack(side=TOP, fill=BOTH, expand=YES) 
self.focus_set() 

Initialize our options 

self.initialiseoptions (AppShel1) 


def appInit (self): 
# Called before interface is created (should be overridden). 
pass 


def initializeTk(self, root): Q 
# Initialize platform-specific options 
if sys.platform == 'mac': 
self.__initializeTk_mac (root) 
elif sys.platform == 'win32': 
self.__initializeTk_win32 (root) 
else: 
self.__initializeTk_unix(root) 





def __initializeTk_colors_common(self, root): 





root.option_add('*background', 'grey') 
root.option_add('*foreground', 'black') 
root.option_add('*EntryField.Entry.background', 'white') 
root.option_add('*MessageBar.Entry.background', 'gray85') 
root.option_add('*Listbox*background', 'white') 
root.option_add('*Listbox*selectBackground', 'dark slate blue') 
root.option_add('*Listbox*selectForeground', 'white') 


def __initializeTk_win32(self, root): 


self.__initializeTk_colors_common (root) 
root.option_add('*Font', 'Verdana 10 bold') 
root.option_add('*EntryField.Entry.Font', 'Courier 10') 
root.option_add('*Listbox*Font', 'Courier 10') 





def __initializeTk_mac(self, root): 
self.__initializeTk_colors_common (root) 


def __initializeTk_unix(self, root): 
self.__initializeTk_colors_common (root) 





Code comments 


@ = AppShell imports ProgressBar. Its code is not shown here, but is available online. 


import ProgressBar 


@ AppShell inherits pmw.MegawWidget since we are constructing a megawidget. 


class AppShell1 (Pmw.MegaWidget ) : 
appversion= '1.0' 
appname = 'Generic Application Frame' 
copyright= 'Copyright YYYY Your Company. All Rights Reserved' 
contactname= 'Your Name' 
contactphone= '(999) 555-1212' 
contactemail= 'youremail@host.com' 
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We then define several class variables which provide default data for the version, title and 
about... information. We assume that these values will be overridden. 


© Default dimensions and padding are supplied. Again we expect that the application will over- 
ride these values. 

frameWidth= 450 

frameHeight= 320 

padx =5 

pady =) 5 

usecommandarea= 0 

balloonhelp= 1 


usecommandarea is used to inhibit or display the command (button) area. 


© Inthe __init__ for AppShell, we build the options supplied by the megawidget. 
def __init__(self, **kw): 








optiondefs = ( 
('padx', Ti, Pmw.INITOPT) 
('pady', i, Pmw. INITOPT), 
('framewidth', 1, Pmw.INITOPT), 
('frameheight', 1,Pmw.INITOPT), 


('usecommandarea', self.usecommandarea, Pmw.INITOPT) ) 
self.defineoptions(kw, optiondefs) 
Pmw.INITOPT defines an option that is available only at initialization—it cannot be set 
with a configure call. (See “Pmw reference: Python megawidgets” on page 542 for more 
information on defining options.) 


@ Nowwe can initialize Tk and Pmw and set the window’s title and geometry: 


self.root = Tk() 
self.initializeTk(self.root) 
Pmw.initialise(self.root) 
self.root.title(self.appname) 


self.root.geometry('%dx%d' % (self.frameWidth, 
self.frameHeight) ) 


© After defining the options and initializing Tk, we call the constructor for the base class: 
Pmw.MegaWidget.__init__(self, parent=self.root) 


@ AppShell is intended to support the major Tkinter architectures; the next few methods define 
the colors and fonts appropriate for the particular platform. 


AppShell.py (continued) 


def busyStart (self, newcursor=None) : O 
if not newcursor: 

newcursor = self.busyCursor LLLLLLLLLL 
newPreBusyCursors = {} 


for component in self.busyWidgets: 
newPreBusyCursors [component] = component['cursor'] 
component. configure (cursor=newcursor) 
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component .update_idletasks () 
self.preBusyCursors = (newPreBusyCursors, self.preBusyCursors) 


def busyEnd(self): 
if not self.preBusyCursors: 
return 
oldPreBusyCursors = self.preBusyCursors [0] 
self.preBusyCursors = self.preBusyCursors[1] 





for component in self.busyWidgets: 
try: 
component. configure (cursor=oldPreBusyCursors [component] ) 
except KeyError: 
pass 
component .update_idletasks () 





def __createAboutBox(self): (9) 
Pmw.aboutversion (self.appversion) 
Pmw.aboutcopyright (self.copyright) 
Pmw.aboutcontact ( 

'For more information, contact:\n %s\n Phone: %s\n Email: %s' %\ 
(self.contactname, self.contactphone, 
self.contactemail)) 
self.about = Pmw.AboutDialog(self._hull, 
applicationname=self.appname) 
self.about.withdraw() 
return None 


def showAbout (self): 
# Create the dialog to display about and contact information. 
self.about.show() 
self.about.focus_set() 


def toggleBalloon(self): © 
if self.toggleBalloonVar.get(): 
self.__balloon.configure(state = 'both') 
else: 
self.__balloon.configure(state = 'status') 


def __createMenuBar (self): D 
self.menuBar = self.createcomponent ('menubar', (), None, 
Pmw.MenuBar, 
(self._hull,), 
hull_relief=RAISED, 
hull_borderwidth=1, 
balloon=self.balloon() ) 
self .menuBar.pack (£i111=xX) 
self.menuBar.addmenu('Help', ‘About %s' % self.appname, side='right') 
self.menuBar.addmenu('File', 'File commands and Quit') 


def createMenuBar (self): 
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self.menuBar.addmenuitem('Help', 'command', 

‘Get information on application', 

label='About...', command=self.showAbout) 
self.toggleBalloonVar = IntVar() 
self.toggleBalloonVar.set (1) 
self.menuBar.addmenuitem('Help', 'checkbutton', 

'Toggle balloon help', 

label='Balloon help', 

variable = self.toggleBalloonVar, 

command=self.toggleBalloon) 


self.menuBar.addmenuitem('File', 'command', 'Quit this application', 
label='Quit', 
command=self.quit) 





Code comments (continued) 


© The next few methods support setting and unsetting the busy cursor: 


def busyStart (self, newcursor=None) : 


© Next we define methods to support the About... functionality. The message box is created 
before it is used, so that it can be popped up when required. 
def __createAboutBox (self): 


@ Balloon help can be useful for users unfamiliar with an interface, but annoying to expert users. 
AppShell provides a menu option to turn off balloon help, leaving the regular status messages 
displayed, since they do not tend to cause a distraction. 

def toggleBalloon(self): 
if self.toggleBalloonVar.get(): 
self.__balloon.configure(state = 'both') 
else: 
self.__balloon.configure(state = 'status') 

@ Menu bar creation is split into two member functions. __createMenuBar creates a Pmw 
MenuBar component and createMenuBar populates the menu with standard options, which 
you may extend as necessary to support your application. 


AppShell.py (continued) 


def __createBalloon(self): ® 
# Create the balloon help manager for the frame. 
# Create the manager for the balloon help 
self.__ balloon = self.createcomponent('balloon', (), None, 
Pmw.Balloon, (self._hull,) ) 


def balloon(self): 
return self.__ balloon 


def __createDataArea(self): ® 
# Create a data area where data entry widgets are placed. 
self.dataArea = self.createcomponent ('dataarea', 
(), None, 
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Frame, (self._hull,), 
relief=GROOVE, 
bd=1) 
self.dataArea.pack(side=TOP, fill=BOTH, expand=YES, 
padx=self['padx'], pady=self['pady'] 


def __createCommandArea(self): D 
# Create a command area for application-wide buttons. 
self.__commandFrame = self.createcomponent('commandframe', (), None, 
Frame, 
(self._hull,), 
relief=SUNKEN, 
bd=1) 
self._ buttonBox = self.createcomponent ('buttonbox', (), None, 


Pmw.ButtonBox, 
(self.__commandFrame, ), 
padx=0, pady=0) 
self._ buttonBox.pack(side=TOP, expand=NO, fi11=xX) 
if self['usecommandarea']: 
self.__commandFrame.pack(side=TOP, 
expand=NO, 
fill=x, 
padx=self['padx'], 
pady=self['pady' ] 


def __createMessageBar (self): O 
# Create the message bar area for help and status messages. 
frame = self.createcomponent ('bottomtray', (), None, 
Frame, (self._hull,), relief=SUNKEN) 

self.__messageBar = self.createcomponent ('messagebar', 

(), None, 

Pmw.MessageBar, 

(frame,), 


#entry_width = 40, 

entry_relief=SUNKEN, 

entry_bd=1, 

labelpos=None) 
self.__messageBar.pack(side=LEFT, expand=YES, f£i11=X) 


self.__progressBar = ProgressBar. ProgressBar (frame, O 
fillColor='slateblue', 
doLabel=1, 
width=150) 
self.__ progressBar.frame.pack(side=LEFT, expand=NO, fi1l1=NONE) 


self .updateProgress (0) 
frame.pack(side=BOTTOM, expand=NO, fi11=X) 


self._ balloon.configure(statuscommand = \ 
self.__messageBar.helpmessage) 


def messageBar (self): 
return self.__messageBar 


def updateProgress(self, newValue=0, newLimit=0): 
self._ progressBar.updateProgress (newValue, newLimit) 
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def bind(self, child, balloonHelpMsg, statusHelpMsg=None) : 
# Bind a help message and/or status message to a widget. 
self.__balloon.bind(child, balloonHelpMsg, statusHelpMsg) 


def interior (self): (17) 
# Retrieve the interior site where widgets should go. 
return self.dataArea 


def buttonBox(self): 
# Retrieve the button box. 
return self.__buttonBox 


def buttonAdd(self, buttonName, helpMessage=None, © 

statusMessage=None, **kw): 

# Add a button to the button box. 

newBtn = self.__buttonBox.add(buttonName) 

newBtn. configure (kw) 

if helpMessage: 
self.bind(newBtn, helpMessage, statusMessage) 

return newBtn 





Code comments (continued) 


The balloon component is created: 


def __createBalloon(self): 
self._ balloon = self.createcomponent('balloon', (), None, 
Pmw.Balloon, (self._hull1,)) 


The dataarea component is simply a frame to contain whatever widget arrangement is 
needed for the application: 


def __createDataArea(self): 
self.dataArea = self.createcomponent ('dataarea', 
(), None, 
Frame, (self._hull,), 
relief=GROOVE 
bd=1) 





The commandarea is a frame containing a Pmw ButtonBox: 
def __createCommandArea (self): 
self.__commandFrame = self.createcomponent('commandframe', (), None, 
Frame, 
(self._hull,), 
relief=SUNKEN, 
bd=1) 
self._ buttonBox = self.createcomponent ('buttonbox', (), None, 
Pmw.ButtonBox, 
(self.__commandFrame, ), 
padx=0, pady=0) 


Similarly, the messagebar is a frame containing a Pmw MessageBox: 


def __createMessageBar (self): 


To complete our major components, we create a progressbar component next to the mes- 
sagebar: 
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self.__progressBar = ProgressBar. ProgressBar (frame, 


@ It is a Pmw convention to provide a method to return a reference to the container where wid- 
gets should be created; this method is called interior: 


def interior(self): 
return self.dataArea 


® It also provides a method to create buttons within the commandarea and to bind balloon and 
status help to the button: 


def buttonAdd(self, buttonName, helpMessage=None, 
statusMessage=None, **kw): 
newBtn = self.__buttonBox.add(buttonName) 
newBtn. configure (kw) 
if helpMessage: 
self.bind(newBtn, helpMessage, statusMessage) 
return newBtn 


AppShell.py (continued) 


def __createInterface(self) : O 
self.__createBalloon() 
self.__createMenuBar () 
self.__createDataArea () 
self.__createCommandArea () 
self.__ createMessageBar () 
self.__createAboutBox () 

# 

# Create the parts of the interface 

# which can be modified by subclasses. 
# 

self.busyWidgets = ( self.root, ) 
self.createMenuBar () 
self.createInterface() 


def createInterface(self): 
# Override this method to create the interface for the app. 
pass 


def main(self): 
self.pack() 
self .mainloop() 


def run(self): 
self.main() 


class TestAppShell (AppShell1) : 
usecommandarea=1 


def createButtons (self): © 
self.buttonAdd('Ok', 
helpMessage='Exit', 
statusMessage='Exit', 
command=self.quit) 








def createMain(self): ð 
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self.label = self.createcomponent('label', (), None, 
Label, 
(self.interior(),), 
text='Data Area') 
self.label.pack() 
self.bind(self.label, 'Space taker') 


def createInterface(self): © 
AppShell.createInterface (self) 
self.createButtons () 
self.createMain() 


if _ name == '_main_': 
test = TestAppShell (balloon_state='both' ) 
test.run() 





Code comments (continued) 


@ _creatertnterface creates each of the standard areas and then calls the createInterface 
method (which is overridden by the application) to complete the population of the various 
areas: 


def __createInterface(self): 
self.__createBalloon() 
self.__createMenuBar () 
self.__createDataArea () 
self.__createCommandArea () 
self.__ createMessageBar () 
self.__createAboutBox () 
self.busyWidgets = ( self.root, ) 
self.createMenuBar () 
self.createInterface () 


@ For this example, we define just one button to exit the application; you would add all of your 
buttons to this method for your application. 
def createButtons (self): 
self.buttonAdd('0Ok', 
helpMessage='Exit', 
statusMessage='Exit', 
command=self.quit) 
@ Again, for the purpose of illustration, the dataarea has not been populated with any more 
than a simple label: 
def createMain (self): 
self.label = self.createcomponent('label', (), None, 
Label, 
(self.interior(),), 
text='Data Area') 
self.label.pack() 
self.bind(self.label, 'Space taker') 


Notice how we define balloon help for the label. 
@ Finally, here is the createInterface method which extends AppShells method: 


def createInterface(self): 
AppShell.createInterface(self) 
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self.createButtons () 
self.createMain() 


If you run AppShell.py, you will see a shell similar to the one in figure 8.8. Look for the 
toggle menu item in the Help menu to enable or disable balloon help. 


Generic Application Frame 


File 


File commands and Quit ita Area 








Help | 







About... 
¥ Balloon help 


ee 


Figure 8.8 AppShell—A standard application framework 








8.3 Data dictionaries 


The forms that I have presented as examples have been coded explicitly for the material to be 
displayed; this becomes cumbersome when several forms are required to support an applica- 
tion. The solution is to use a data dictionary which defines fields, labels, widget types and 
other information. In addition, it may provide translation from database to screen and back to 
database, and define validation requirements, editable status and other behavior. We will see 
some more complete examples in “Putting it all together...” on page 311. However, the exam- 
ples presented here will certainly give you a clear indication of their importance in simplifying 
form design. 

First let’s take a look at a simple data dictionary; in this case it really zs a Python dictionary, 
but other data structures could be used. 


datadictionary.py 


LC =1 # Lowercase Key 1) 

UC = 2 # Uppercase Key 

XX = 3 # As Is 

DT = 4 # Date Insert 

ND = 5 # No Duplicate Keys 

ZP = 6 # Pad Zeroes 

ZZ, =. 7 # Do Not Display 

ZS = 8 # Do Not display, but fill in with key if blank 


BLANKOK = 0 # Blank is valid in this field 


DATA DICTIONARIES 165 











166 


© 


NONBLANK = 1 # Field cannot be blank 


dataDict = { 

'crewmembers': ('crewmembers', 0.11, 0.45, 0.05, [ O 
('Employee #', 'employee_no', 9, XX, 'valid_blank', NONBLANK) @ 
('PIN', 'pin', 4, XX, '', BLANKOK), 

('Category', 'type', 1, UC, 'valid_category', NONBLANK) , 
('SSN #', 'ssn', 9, XX, 'valid_ssn', BLANKOK), 
('First Name', 'firstname', 12, XX, 'valid_blank', NONBLANK) , 
('Middle Name', 'middlename', 10, XX, '', BLANKOK), 
('Last Name', '‘'lastname', 20, XX, 'valid_blank', NONBLANK) , 
('Status', 'status', 1, UC, '', BLANKOK), 
('New Hire', 'newhire', 1, UC, 'valid_y_n_blank', BLANKOK) , 
('Seniority Date', 'senioritydate', 8, XX, 'valid_blank', NONBLANK) , 
('Seniority', 'seniority', 5, XX, 'valid_blank', NONBLANK) , 
('Base', 'base', 3, UC, 'valid_base', NONBLANK), 
('Language 1', '‘langl', 2, UC, 'valid_lang', BLANKOK), 
('Language 2', ‘lang2', 2, UC, 'valid_lang', BLANKOK), 
('Language 3', '‘lang3', 2, UC, 'valid_lang', BLANKOK), 
('Language 4', '‘lang4', 2, UC, 'valid_lang', BLANKOK), 
('Language 5', ‘lang5', 2, UC, 'valid_lang', BLANKOK), 
('Language 6', '‘lang6', 2, UC, 'valid_lang', BLANKOK)], 

'Crew Members', [0]), O 

'crewqualifications': ('crewqualification',0.25,0.45,0.075, [ 
('Employee #', '‘employee_no', 9, XX, '', BLANKOK), 

('Equipment', 'equipment', 3, UC, '', BLANKOK), 

('Eqpt. Code' ‘equipmentcode', 1, UC, '', BLANKOK), 

('Position' reba EE Otis 2, UC, '', BLANKOKR), 

('Pos. Code , ‘'positioncode', 2, UC, '', BLANKOK), 

('Reserve', 'reserve', 1, UC, 'valid_r_blank', BLANKOK) , 

('Date of Hire' "hiredate', 8, UC, '', BLANKOK), 

('End Date' venddate®, 8, UC, '', BLANKOK), 

('Base Code "basecode', 1, UC, '', BLANKOK), 

('Manager' mananari 1, UC, 'valid_y_n_blank', BLANKOK)], 
'Crew Qualifications', [0]) } 





Code comments 


We define several constants to characterize the behavior of entry fields, controlling case- 
changing, for example: 


LC = 1 # Lowercase Key 
UC = 2 # Uppercase Key 
XX = 3 # As Is 


The first section of each entry in the dictionary defines the key, database table and layout data 
to customize the position of the first line, label/field position and the line spacing respectively. 
‘crewmembers': ('crewmembers', 0.11, 0.45, 0.05, [ 


Each entry in the dictionary defines the label, database key, field length, entry processing, val- 
idation and whether the field may be left blank. 


('Employee #', 'employee_no', 9, XX, 'valid_blank', NONBLANK) , 
('PIN', 'pin', 4, XX, '', BLANKOK), 
('Category', 'type', 1, UC, 'valid_category', NONBLANK) , 
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© The final entry in each table defines the title and a list of indices for the primary and second- 
ary keys (in this case, we are only using a single key): 
‘Crew Members', [0]), 


Now let’s use datadictionary.py to create an interface. We will also use AppShell to pro- 
vide the framework. 


Example_8_7.py 


from Tkinter import * 

import Pmw 

import os 

import AppShell 

from datadictionary import * 


class DDForm(AppShell.AppShell) : o 
usecommandarea = 1 
appname = 'Update Crew Information' 
dictionary = 'crewmembers' 
frameWidth = 600 
frameHeight = 590 
def createButtons(self): O 


self.buttonAdd('Save', 
helpMessage='Save current data', 
statusMessage='Write current information to database', 
command=self.unimplemented) 
self.buttonAdd('Undo', 
helpMessage='Ignore changes', 
statusMessage='Do not save changes to database', 
command=self.unimplemented) 
self .buttonAdd('New', 
helpMessage='Create a New record', 
statusMessage='Create New record', 
command=self.unimplemented) 
self.buttonAdd('Delete', 
helpMessage='Delete current record', 
statusMessage='Delete this record', 
command=self.unimplemented) 
self.buttonAdd('Print', 
helpMessage='Print this screen', 
statusMessage='Print data in this screen', 
command=self.unimplemented) 
self. buttonAdd('Prev', 
helpMessage='Previous record', 
statusMessage='Display previous record', 
command=self.unimplemented) 
self.buttonAdd('Next', 
helpMessage='Next record', 
statusMessage='Display next record', 
command=self.unimplemented) 
self.buttonAdd('Close', 
helpMessage='Close Screen', 
statusMessage='Exit', 





DATA DICTIONARIES 167 











command=self.unimplemented) 


def createForm(self): 
self.form = self.createcomponent('form', (), None, 
Frame, (self.interior(),),) 
self.form.pack(side=TOP, expand=YES, f£i11=BOTH) 
self.formwidth = self.root.winfo_width() 





def createFields(self): 
self.table, self.top, self.anchor, self.incr, self.fields, \ 
self.title, self.keylist = dataDict[self.dictionary] 
self.records= [] 
self.dirty= FALSE 
self.changed= [] 
self.newrecs= [] 
self.deleted= [] 
self.checkDupes = FALSE 
self.delkeys= [] 


self.ypos = self.top O 
self.recrows = len(self.records) 
if self.recrows < 1: # Create one! 
self.recrows = 1 
trec = [] 
for i in range(len(self.fields) ): 
trec.append (None) 
self.records.append((trec) ) 


Label(self.form, text=self.title, width=self.formwidth-4, QO 
bd=0) .place(relx=0.5, rely=0.025, anchor=CENTER) 

self.lmarker = Label(self.form, text="", bd=0, width=10) 

self.lmarker.place(relx=0.02, rely=0.99, anchor=SW) 

self.rmarker = Label(self.form, text="", bd=0, width=10) 

self.rmarker.place(relx=0.99, rely=0.99, anchor=SE) 





self.current = 0 


idx = 0 
for label, field, width, proc, valid, nonblank in self.fields: QO 
pstr = 'Label(self.form, text="%s") .place(relx=%f,rely=%f,'\ 


‘anchor=E) \n' % (label, (self.anchor-0.02), self.ypos) 
if idx == self.keylist[0]: 
pstr = '%sself.%s=Entry(self.form,text="",'\ 
'insertbackground="yellow", width=%d+1,'\ 
"highlightthickness=1)\n' % (pstr,field,width) 
else: 
pstr = '%sself.%s=Entry(self.form,text="",'\ 
'insertbackground="yellow",'\ 
'width=%d+1)\n' % (pstr,field,width) 
pstr = '%sself.%s.place(relx=%f, rely=%f,' 
‘anchor=W) \n' % (pstr,field, (self.anchor+0.02),self.ypos) 
exec '%Ssself.%sV=StringVar()\n'\ 
'self.%s["textvariable"] = self.%sv' % \ 
(pstr, field, field, field) 
self.ypos = self.ypos + self.incr 
idx = idx +1 
self .update_display () 
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def update_display(self): (8) 

idx = 0 

for label, field, width, proc, valid, nonblank 
v=self.records[self.current] [idx] 
ah not vis! 
exec 'self.%3sV.set(v)' 
idx = idx + 1 

if self.current in self.deleted: 
self.rmarker['text'] 'Deleted' 

elif self.current in self.newrecs: 


in self.fields: 


% field 


self.rmarker['text'] = 'New' 
else: 
self.rmarker['text'] = '' 
if self.dirty: 
self.ilmarker['text'] = "Modified" 


self.lmarker['foreground'] = "#FF3333" 
else: 

self.ilmarker['text'] =." 

self.lmarker['foreground'] = "#00FF44" 


# We'll set focus on the first widget 
label, field, width, proc, valid, nonblank 
exec 'self.%s.focus_set()' % field 


© 


© 


self.fields[0] 


def unimplemented (self): 
pass 


def createInterface (self): 
AppShell.AppShell.createInterface (self) 
self.createButtons () 
self.createForm() 
self.createFields() 
if _name__ == '_main_': 
ddform = DDForm() 
ddform. run () 





Code comments 


First we define the Application class, inheriting from AppShell and overriding its class vari- 
ables to set the title, width, height and other values: 
class DDForm(AppShell.AppShell1): 


usecommandarea = 1 

appname = 'Update Crew Information' 
dictionary = 'crewmembers' 

frameWidth = 600 

frameHeight = 590 


@ In this example, we are defining a more realistic complement of control buttons: 


def createButtons (self): 
self.buttonAdd('Save', 
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helpMessage='Save current data', 
statusMessage='Write current information to database', 
command=self.save) 
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Rather than use the default megawidget interior, we create our own form component: 


def createForm(self): 
self.form = self.createcomponent('form', (), None, 
Frame, (self.interior(),),) 
self.form.pack(side=TOP, expand=YES, f£i11=BOTH) 
self.formwidth = self.root.winfo_width() 





We extract the data from the selected data dictionary element and initialize data structures: 


def createFields(self): 
self.table, self.top, self.anchor, self.incr, self.fields, \ 
self.title, self.keylist = dataDict[self.dictionary] 
self.records= [] 
self.dirty= FALSE 


This example does not interface with any database, but we still need to create a single empty 
record even for this case. We create one empty entry for each field: 


self.ypos = self.top 
self.recrows = len(self.records) 
if self.recrows < 1: # Create one! 
self.recrows = 1 
trec = [] 
for i in range(len(self.fields)): 
trec.append (None) 
self.records.append((trec) ) 


Although we are not going to be able to save any information input to the form, we still define 
markers at the left- and right-bottom of the screen to indicate when a record has been modi- 


fied or added: 


Label (self.form, text=self.title, width=self.formwidth-4, 
bd=0) .place(relx=0.5, rely=0.025, anchor=CENTER) 














self.lmarker = Label(self.form, text="", bd=0, width=10) 
self.lmarker.place(relx=0.02, rely=0.99, anchor=SW) 
self.rmarker = Label(self.form, text="", bd=0, width=10) 





self.rmarker.place(relx=0.99, rely=0.99, anchor=SE) 


This is where we create the label/field pairs which make up our interface. We give the user a 
visual clue that a field is the key by increasing the highlight thickness: 


for label, field, width, proc, valid, nonblank in self.fields: 

pstr = 'Label(self.form, text="%s") .place(relx=%f,rely=%f,'\ 

‘anchor=E)\n' % (label, (self.anchor-0.02), self.ypos) 

if idx == self.keylist[0]: 
pstr = '%sself.%s=Entry(self.form,text="",'\ 
'insertbackground="yellow", width=%d+1,'\ 
‘highlightthickness=1)\n' % (pstr,field,width) 

else: 





Note In this application we have chosen to use highlightthickness to provide a 

visual clue to the user that the field contains the key to the data. You might 
choose one of several other methods to get this effect, such as changing the background 
color or changing the borderwidth. 
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The update_display method is responsible for setting the markers to indicate new, deleted 
and modified records: 
def update_display(self): 
idx = 0 
for label, field, width, proc, valid, nonblank in self.fields: 
v=self.records[self.current] [idx] 
if not v:v="" 
exec 'self.%sV.set(v)' % field 
idx = idx +1 
if self.current in self.deleted: 


© The methods bound to the control buttons do nothing in our example, but they are required 
for Python to run the application: 


def unimplemented(self): 
pass 


Running Example_8_7.py will display a screen similar to figure 8.9. Notice that the lay- 
out could be improved if the fields were individually placed, or if more than one field were 
placed on a single line, but that would obviate the simplicity of using a data dictionary. 
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Figure 8.9 A screen created from a data dictionary 
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8.4 


Notebooks 


Notebooks (sometimes referred to as style or property sheets) have become a common motif for 
user interfaces. One large advantage is that they allow the form designer to display a large 
number of entry fields without overwhelming the user. Additionally, the fields can be 
arranged in related groupings, or less-important fields can be separated from fields which are 
frequently changed. 


The next example demonstrates the use of notebooks, data dictionaries and AppShell to 


present the same basic data in Example_8_7.py on three separate notebook panes. 
datadictionary.py has been rearranged as datadictionary2.py, but it will not be presented 
here (the previous dictionary has been divided into one section for each pane of the notebook). 


Example_8_ 9.py 


from Tkinter import * 

import Pmw 

import os 

import AppShell 

from datadictionary2 import * 


class DDNotebook (AppShell.AppShel1): 


usecommandarea = 1 


appname = 'Update Crew Information' 
dictionary = 'crewmembers' 

frameWidth = 435 

frameHeight = 520 


def createButtons (self): 

self.buttonAdd('Save', 
helpMessage='Save current data', 
statusMessage='Write current information to database', 
command=self.save) 

self.buttonAdd('Close', 
helpMessage='Close Screen', 
statusMessage='Exit', 
command=self.close) 


def createNotebook (self): 

self.notebook = self.createcomponent ('notebook', (), None, 
Pmw.NoteBookR, (self.interior(),),) 
self .notebook.pack(side=TOP, expand=YES, fi11=BOTH, padx=5, pady=5) 
self.formwidth = self.root.winfo_width() 





def addPage(self, dictionary) : 

table, top, anchor, incr, fields, \ 
title, keylist = dataDict [dictionary] 
self.notebook.add(table, label=title) 
self.current = 0 





ypos = top 

idx= 0 

for label, field, width, proc, valid, nonblank in fields: © 
pstr = 'Label(self.notebook.page(table).interior(),'\ 
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'text="%s").place(relx=%f,rely=%f, anchor=E)\n' % \ 
(label, (anchor-0.02), ypos) 
if idx == keylist[0]: 
pstr = '%sself.%s=Entry(self.notebook.page(table) .\ 
‘interior(), text="",insertbackground="yellow"', 
‘width=%d+1, highlightthickness=1)\n' % \ 
(pstr, field, width) 








else: 
pstr = '%sself.%s=Entry(self.notebook.page(table) .\ 
‘interior(), text="", insertbackground="yellow",' 
'width=%d+1)\n' % (pstr,field,width) 
pstr = '%sself.%s.place(relx=%f, rely=%f,'\ 


‘anchor=W) \n' % (pstr,field, (anchor+0.02) ,ypos) 
exec '%sself.%sV=StringVar()\n'\ 
'self.%s["textvariable"] = self.%sv' % (pstr,field, field, field) 
ypos = ypos + incr 
idx = idx +1 


def createPages (self): (4) 
self.addPage ('general') 
self.addPage('language' ) 
self.addPage('crewqualifications') 
self.update_display() 


def update_display(self): 
pass 


def save(self): 
pass 

def close(self): 
self.quit() 


def createInterface(self): 
AppShell.AppShell.createInterface (self) 
self.createButtons () 
self.createNotebook () 
self.createPages () 


if _ name == '_main_': 
ddnotebook = DDNotebook() 
ddnotebook. run () 





Code comments 


@ Creating a notebook within the AppShell is simply a case of creating a Pmw NoteBookR com- 

ponent. 
def createNotebook (self) : 
self.notebook = self.createcomponent ('notebook', (), None, 
Pmw.NoteBookR, (self.interior(),),) 

self .notebook.pack(side=TOP, expand=YES, fil1l=BOTH, padx=5, pady=5) 

Pmw provides an alternate notebook widget, NoteBooks (see figure 8.10 on page 174 

for an example). I do not recommend that you use this widget since it has a generally inferior 
layout. 
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def addPage(self, dictionary): 
table, top, anchor, incr, fields, \ 
title, keylist = dataDict [dictionary] 


self.notebook.add(table, label=title) 


Loading the fields from the data dictionary is similar to the previous example: 


The name and text displayed in the notebook tab comes directly from the data dictionary: 


for label, field, width, proc, valid, nonblank in fields: 
pstr = 'Label(self.notebook.page(table).interior(),'\ 
‘'text="%s") .place(relx=%f,rely=%f, anchor=E)\n' % \ 





(label, (anchor-0.02), ypos) 


The pages are tagged with the dictionary key: 


def createPages(self): 
self .addPage('general' ) 
self.addPage('language' ) 
self.addPage('crewqualifications' ) 
self.update_display() 


Figure 8.10 shows the result of running Example_8_9.py. Notice how the fields are much 


less cluttered and that they now have clear logical groupings. 





General Information | Languages | Crew Qualifications General Information | Languages | Crew Qualifications 
Employee # [12345 Employee # [i2345 
PIN [s866 Equipment [747 
Category |p Eqpt. Code a 
SsN# [010111234 Position [cA 
First Name [Micha Pos. Code fi 
Middle Name jas Reserve In 
Last Name [Marston s—~—S Date of Hire [19910521 
Status |a End Date [|20001231 
New Hire In Base Code ja 
Seniority Date [19910521 Manager In 
Seniority fiz21 
Base |ATW 

















Figure 8.10 Notebooks 
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8.5 Browsers 


Browsers have become a popular motif for navigating information that is, or can be, organized 
as a hierarchy. Good examples of browsers include the Preferences editor in Netscape and 
Windows Explorer. The advantage of browsers is that branches of the typical tree display can 
be expanded and collapsed, resulting in an uncluttered display, even though the volume of 
data displayed can be quite high. 

As an example, we are going to develop a simple image browser which will display all of 
the images in a particular directory. Tk, and therefore Tkinter, supports three image formats: 
GIF, PPM (truecolor), and XBM. To extend the capability of the example, we will use PIL 
from Secret Labs A.B. to build the images. This does not add a great deal of complexity to the 
example, as you will see when we examine the source code. 

The browser uses several icons to represent various file types; for the purpose of this exam- 
ple we are using a mixture of icons created for this application. They are similar in style to those 
found in most current window systems. 

The tree browser class is quite general and can readily be made into a base class for other 
browsers. 


Example_8_10.py 


from Tkinter import * 
import Pmw 

import os 

import AppShell 


import Image, ImageTk 1) 
path = "./icons/" 
imgs = "./images/" 
class Node: O 


def __init__(self, master, tree, icon=None, 
openicon=None, name=None, action=None) : 
self.master, self.tree = master, tree 
self.icon = PhotoImage(file=icon) 
if openicon: 
self.openicon = PhotoImage(file=openicon) 
else: 
self.openicon = None 


self.width, self.height = 1.5*self.icon.width(), \ 
1.5*self.icon.height () 
self.name = name 


self.var = StringVar() © 
self.var.set (name) 
self.text = Entry(tree, textvariable=self.var, bg=tree.bg, 


bd=0, width=len(name)+2, font=tree.font, 
fg=tree.textcolor, insertwidth=1, 
highlightthickness=1, 
highlightbackground=tree.bg, © 
selectbackground="#044484", 
selectborderwidth=0, 
selectforeground='white' ) 
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self.action = action 

self.x = self.y = 0 #drawing location 
self.child = [] 

self.state = 'collapsed' 

self.selected = 0 


def addChild(self, tree, icon=None, openicon=None, name=None, O 
action=None) : 
child = Node(self, tree, icon, openicon, name, action) 
self.child.append (child) 
self.tree.display() 
return child 


def deleteChild(self, child): 
self.child. remove (child) 
self.tree.display() 


def textForget (self): 
self.text.place_forget () 
for child in self.child: 
child.textForget () 


def deselect (self): 
self.selected = 0 
for child in self.child: 
child.deselect () 


def boxpress(self, event=None) : O 
if self.state == 'expanded': 
self.state = 'collapsed' 
elif self.state == 'collapsed': 
self.state = 'expanded' 


self.tree.display () 


def invoke(self, event=None) : QO 
if not self.selected: 
self.tree.deselectall () 
self.selected = 1 
self.tree.display() 
if self.action: 
self.action(self.name) 
self.name = self.text.get() 
self.text.config(width=len(self.name) +2) 





Code comments 

We begin by importing PIL modules: 

import Image, ImageTk 

The Node class defines the subordinate tree and the open and closed icons associated with the 
node. 


class Node: 
def __init__(self, master, tree, icon=None, 
openicon=None, name=None, action=None) : 
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Each node has a Tkinter variable assigned to it since we are going to allow the nodes to be 
renamed (although code to use the new name is not provided in the example): 


self .name name 


self.var = StringVar () 
self.var.set (name) 
self.text = Entry(tree, textvariable=self.var, bg=tree.bg, 





The Entry widget does not display a highlight by default. To indicate that we are editing the 
filename, we add a highlight. 


When we construct the hierarchy of nodes later, we will use the addchild method in the 
Node class: 


def addChild(self, tree, 
action=None) : 
child = Node(self, tree, 
self.child.append (child) 
self.tree.display() 
return child 


icon=None, openicon=None, name=None, 


icon, openicon, name, action) 


This creates an instance of Node and appends it to the child list. 
The boxpress method toggles the state of nodes displayed in the browser; clicking on + 
expands the node, while clicking on —collapses the node. 


def boxpress(self, event=None): 


if self.state == 'expanded': 
self.state = 'collapsed' 

elif self.state == 'collapsed': 
self.state = 'expanded' 

self.tree.display() 


If the node is not currently selected, invoke supports an action assigned to either clicking or 
double-clicking on a node in the tree. For example, it might open the file using an appropriate 
target. 


def invoke(self, event=None) : 

if not self.selected: 
self.tree.deselectall () 
self.selected = 1 
self.tree.display() 
if self.action: 

self.action(self.name) 
self.name self.text.get() 
self.text.config (width=len(self.name) +2) 


Example_8_10.py (continued) 
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def displayIconText (self): 


tree, text = self.tree, self.text 
if self.selected and self.openicon: 
self.pic = tree.create_image(self.x, self.y, 
image=self.openicon) 
else: 
self.pic = tree.create_image(self.x, self.y, 
image=self.icon) 
text.place(x=self.x+self.width/2, y=self.y, anchor=W) 
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text.bind("<ButtonPress-1>", self.invoke) 
tree.tag_bind(self.pic, "<ButtonPress-1>", self.invoke, "+") 
text .bind("<Double-Button-1>", self.boxpress) 
tree.tag_bind(self.pic, "<Double-Button-1>", 

self.boxpress, "+") 


def displayRoot (self): 
if self.state == 'expanded': 
for child in self.child: 
child.display () 
self.displayIconText () 


def displayLeaf (self) : (9) 
self.tree.hline(self.y, self.master.x+1, self.x) 
self.tree.vline(self.master.x, self.master.y, self.y) 
self.displayIconText () 


def displayBranch(self): © 
master, tree = self.master, self.tree 
x, y = self.x, self.y 
tree.hline(y, master.x, x) 
tree.vline(master.x, master.y, y) 
if self.state == 'expanded' and self.child != []: 
for child in self.child: 
child.display () 
box = tree.create_image(master.x, y, 
image=tree.minusnode) 
elif self.state == 'collapsed' and self.child != []: 
box = tree.create_image(master.x, y, 
image=tree.plusnode) 
tree.tag_bind(box, "<ButtonPress-1>", self.boxpress, "+") 
self.displayIconText () 


def findLowestChild(self, node): © 
if node.state == 'expanded' and node.child != []: 
return self.findLowestChild(node.child[-1]) 
else: 
return node 


def display(self): 
master, tree = self.master, self.tree 
n = master.child.index(self) 
self.x = master.x + self.width 
R n =E 
self.y = master.y + (n+1)*self.height 
else: 
previous = master.child[n-1] 
self.y = self.findLowestChild(previous).y + self.height 


if master == tree: 
self.displayRoot () 
elif master.state == 'expanded': 
if self.child == []: 
self.displayLeaf () 
else: 
self.displayBranch () 


178 CHAPTER 8 DIALOGS AND FORMS 








BROWSERS 





tree. lower('line') 


class Tree (Canvas): 
def _ init_ (self, master, icon, openicon, treename, action, 

bg='white', relief='sunken', bd=2, 
linecolor='#808080', textcolor='black', 
font=('MS Sans Serif', 8)): 

Canvas.__init__ (self, master, bg=bg, relief=relief, bd=bd, 

highlightthickness=0) 
self.pack(side='left', anchor=NW, fill='both', expand=1) 


self.bg, self.font= bg, font 

self.linecolor, self.textcolor= linecolor, textcolor 

self.master = master 

self.plusnode = PhotoImage(file=os.path.join(path, 'plusnode.gif') ) 
self.minusnode = PhotoImage(file=os.path.join(path, 'minusnode.gif') ) 
self.inhibitDraw = 1 12) 

self.imageLabel = None 

self.imageData = None 

self.child = [] 

self.x = self.y = -10 


self.child.append( Node( self, self, action=action, 
icon=icon, openicon=openicon, name=treename) ) 


def display(self): 
if self.inhibitDraw: return 
self.delete (ALL) 
for child in self.child: 
child.textForget () 
child.display() 


def deselectall(self): 
for child in self.child: 
child.deselect () 


def vline(self, x, y, yl): © 
for i in range(0, abs(y-yl), 2): 
self.create_line(x, y+i, x, y+i+1, fill=self.linecolor, 
tags='line') 


def hline(self, y, x, x1): 
for i in range(0, abs(x-x1), 2): 
self.create_line(x+i, y, x+tit+l, y, fill=self.linecolor, 
tags='line') 





Code comments (continued) 


displayIcontext displays the open or closed icon and the text associated with the node, 
and it binds single- and double-button-clicks to the text field: 
def displayIconText (self): 
tree, text = self.tree, self.text 
if self.selected and self.openicon: 
self.pic = tree.create_image(self.x, self.y, 
image=self.openicon) 
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text.bind("<ButtonPress-1>", self.invoke) 
tree.tag_bind(self.pic, "<ButtonPress-1>", self.invoke, "+") 
text.bind("<Double-Button-1>", self.boxpress) 
tree.tag_bind(self.pic, "<Double-Button-1>", 

self.boxpress, "+") 


© displayLeat draws a horizontal and vertical line connecting the icon with the current place 
in the tree: 


def displayLeaf (self): 
self.tree.hline(self.y, self.master.x+1, self.x) 
self.tree.vline(self.master.x, self.master.y, self.y) 
self.displayIconText () 


@ Similarly, disp1layBranch draws the lines and an open or closed box: 


def displayBranch(self): 
master, tree = self.master, self.tree 
x, y = self.x, self.y 
tree. hline(y, master.x, x) 
tree.vline(master.x, master.y, y) 
if self.state == 'expanded' and self.child != []: 
for child in self.child: 
child.display() 
box = tree.create_image(master.x, y, 
image=tree.minusnode) 
elif self.state == 'collapsed' and self.child != []: 
box = tree.create_image(master.x, y, 
image=tree.plusnode) 
tree.tag_bind(box, "<ButtonPress-1>", self.boxpress, "+") 
self.displayIconText () 


@ findLowestchild is a recursive method that finds the lowest terminal child in a given 
branch: 


def findLowestChild(self, node): 
if node.state == 'expanded' and node.child != []: 
return self.findLowestChild(node.child[-1]) 
else: 
return node 
@ We define a flag called inhibitDraw to prevent the tree from being redrawn every time we 
add a node. This speeds up the time it takes to construct a complex tree by saving many CPU 
cycles: 
self.inhibitDraw = 1 


@ viine and hline are simple routines to draw vertical and horizontal lines: 


def vline(self, x, y, y1): 
for i in range(0, abs(y-yl), 2): 
self.create_line(x, y+i, x, y+i+1, fill=self.linecolor, 
tags='line') 


Example_8_10.py (continued) 


class ImageBrowser (AppShell.AppShell1): 
usecommandarea=1 
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appname = 'Image Browser' 
def createButtons(self): 
self.buttonAdd('Ok', 
helpMessage='Exit', 
statusMessage='Exit', 
command=self.quit) 








def createMain(self): 
self.panes = self.createcomponent('panes', (), None, 
Pmw.PanedWidget, 
(self.interior(),), 
orient='horizontal') 
self.panes.add('browserpane', min=150, size=160) 
self.panes.add('displaypane', min=.1) 


f£ = os.path.join(path, 'folder.gif') 
of = os.path.join(path, 'openfolder.gif') 


self.browser = self.createcomponent('browse', (), None, 
Tree, 
(self.panes.pane('browserpane'),), 
icon=f, 


openicon=of, 
treename='Multimedia', 
action=None) 

self .browser.pack(side=TOP, expand=YES, fil1=yY) 


self.datasite = self.createcomponent('datasite', (), None, 
Frame, 
(self.panes.pane('displaypane'),)) 


self.datasite.pack(side=TOP, expand=YES, fill=BOTH) 


f = os.path.join(path, 'folder.gif') © 
of = os.path.join(path, 'openfolder.gif') 

gf = os.path.join(path, 'gif.gif') 

jf = os.path.join(path, 'jpg.gif') 

xf = os.path.join(path, 'other.gif') 


self.browser.inhibitDraw = 1 


top=self.browser.child[0] 

top.state='expanded' 

jpeg=top.addChild(self.browser, icon=f, openicon=of, 
name='Jpeg',action=None) 

gif=top.addChild(self.browser, icon=f, openicon=of, 
name='GIF', action=None) 

other=top.addChild(self.browser, icon=f, openicon=of, 

name='Other', action=None) 


imageDir = { '.jpg': (jpeg, jf), '.jpeg': (jpeg, jf), O 
gifi (gify GE), comp'4 (other, xf), 
'.ppm': (other, xf)} 

files = os.listdir(imgs) © 


for file in files: 
r, ext = os.path.splitext (file) 
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cont, icon = imageDir.get(ext, (None, None) ) 
if cont: 
cont.addChild(self.browser, icon=icon, 
name=file, action=self.showMe) 
self.browser.inhibitDraw = 0 © 
self.browser.display () 
self.panes.pack(side=TOP, expand=YES, fi11=BOTH) 





def createImageDisplay(self): 
self.imageDisplay = self.createcomponent('image', (), None, 

Label, 

(self.datasite, ) ) 
self.browser.imageLabel = self.imageDisplay 
self.browser.imageData= None 
self.imageDisplay.place(relx=0.5, rely=0.5, anchor=CENTER) 











def createInterface(self): 
AppShell .AppShell.createInterface (self) 
self.createButtons () 
self.createMain() 
self.createImageDisplay () 


def showMe(self, dofile): 
if self.browser.imageData: del self.browser.imageData 
self.browser.imageData = ImageTk.PhotoImage(\ 
Image.open('%s%s' % \ 
(imgs, dofile))) 
self .browser.imageLabel['image'] = self.browser.imageData 


if _ name == '_ main_': 
imageBrowser = ImageBrowser () 
imageBrowser.run () 





Code comments (continued) 


@ We define all of the icons that may be displayed for each file type: 
f£ = os.path.join(path, 'folder.gif') 
of = os.path.join(path, 'openfolder.gif') 
gf = os.path.join(path, 'gif.gif') 
jf = os.path.join(path, 'jpg.gif') 
xf = os.path.join(path, '‘other.gif') 
@® Now the root of the tree is created and we populate the root with the supported image types: 
top=self.browser.child[0] 
top.state='expanded’ 
jpeg=top.addChild(self.browser, icon=f, openicon=of, 
name='Jpeg',action=None) 


@ We create a dictionary to provide translation from file extensions to an appropriate image type 
and icon (dictionaries are an efficient way of determining properties of an object which have 
varied processing requirements). 

imageDir = { '.jpg': (jpeg, jf), '.jpeg': (jpeg, jf), 
'.gif': (gif, gf), '.bmp': (other, xf), 
'.,ppm': (other, xf) } 
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@_ We scan the disk, finding all files with recognizable extensions and add the nodes to the tree: 
files = os.listdir(imgs) 
for file in files: 
r, ext = os.path.splitext (file) 
cont, icon = imageDir.get(ext, (None, None) ) 
if cont: 
cont.addChild(self.browser, icon=icon, 
name=file, action=self.showMe) 
This code would probably be a little more complex in reality; I can see a couple of poten- 
tial problems as I’m writing this (I could write “I leave this as an exercise for you to identify 
problems with this code”). 


@ Once the tree has been built, we reset the inhibitDraw flag and display the tree: 
self.browser.inhibitDraw = 0 
self.browser.display () 
That probably seems like a lot of code, but the resulting browser provides a highly- 
acceptable interface. In addition, users will understand the interface’s navigation and it is 
readily adaptable to a wide range of data models. 


Running Example_8_10.py (with a Python built with PIL) will display a screen similar 
to the one in figure 8.11. 


( Multimedia 
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Figure 8.11 Image browser 
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8.6 Wizards 


Windows 95/98/NT users have become familiar with wizard interfaces since they have 
become prevalent with installation and configuration tools. Wizards guide the user through a 
sequence of steps, and they allow forward and backward navigation. In many respects they are 
similar to Notebooks, except for their ordered access as opposed to the random access of the 
Notebook. 

This example illustrates a wizard that supports software installation. WizardShell.py is 
derived from AppShell.py, but it has sufficient differences to preclude inheriting AppShell’s 
properties. However, much of the code is similar to AppShell and is not presented here; the 
complete source is available online. 


WizardShell.py 


from Tkinter import * 
import Pmw 
import sys, string 


class WizardShell (Pmw.MegaWidget) : 
wizversion= '1.0' 
wizname = 'Generic Wizard Frame' 
wizimage= 'wizard.gif' 


panes avd o 
def _ init_ (self, **kw): 
optiondefs = ( 
('framewidth', dy Pmw.INITOPT) , 
('frameheight', 1, Pmw.INITOPT) ) 


self.defineoptions(kw, optiondefs) 


# setup panes O 
self.pCurrent = 0 
self.pFrame = [None] * self.panes 


def wizardInit (self): 
# Called before interface is created (should be overridden). 


pass © 
def __createWizardArea(self): 
self.__wizardArea = self.createcomponent ('wizard',(), None, 
Frame, (self._hull,), 
relief=FLAT, bd=1) 





self.__ illustration = self.createcomponent ('illust',(), None, 
Label, (self.__wizardArea, ) ) 

self.__illustration.pack(side=LEFT, expand=NO, padx=20) 

self.__wizimage = PhotoImage(file=self.wizimage) 

self.__illustration['image'] = self.__wizimage 

self.__dataArea = self.createcomponent ('dataarea',(), None, 
Frame, (self.__wizardArea,), 
relief=FLAT, bd=1) 

self._ dataArea.pack(side=LEFT, fill = 'both', expand = YES) 
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self.__wizardArea.pack(side=TOP, fill=BOTH, expand=YES) 


def __createSeparator(self): 
self.__ separator = self.createcomponent('separator',(), None, 
Frame, (Sself._hull,), 
relief=SUNKEN, 
bd=2, height=2) 
self.__ separator.pack(fill=xX, expand=YES) 


def __createCommandArea(self): 
self._._commandFrame = self.createcomponent ('commandframe',(), None, 
Frame, (self._hull,), 
relief=FLAT, bd=1) 
self.__commandFrame.pack(side=TOP, expand=NO, f£i11=X) 


def interior(self): 
return self.__dataArea 


def changePicture(self, gif): 
self.__wizimage = PhotoImage(file=gif) 
self.__illustration['image'] = self.__wizimage 


def buttonAdd(self, buttonName, command=None, state=1): O 
frame = Frame(self.__commandFrame) 
newBtn = Button(frame, text=buttonName, command=command) 
newBtn.pack() 
newBtn['state'] = [DISABLED,NORMAL] [state] 
frame.pack(side=RIGHT, ipadx=5, ipady=5) 
return newBtn 


def __createPanes (self): O 
for i in range(self.panes) : 
self.pFrame[i] = self.createcomponent('pframe',(), None, 


Frame, (self.interior(),), 
relief=FLAT, bd=1) 
if not i == self.pCurrent: 
self.pFrame[i].forget() 
else: 
self.pFrame[i].pack(f£ill=BOTH, expand=YES) 


def pInterior (self, idx): QO 
return self.pFrame[idx] 


def next (self): Q 
cpane = self.pCurrent 
self.pCurrent = self.pCurrent + 1 
self.prevB['state'] = NORMAL 


if self.pCurrent == self.panes - 1: 
self.nextB['text'] = 'Finish' 
self.nextB['command'] = self.done 


self.pFrame[cpane].forget() 
self.pFrame[self.pCurrent].pack(fill=BOTH, expand=YES) 


def prev(self): 


cpane = self.pCurrent 
self.pCurrent = self.pCurrent - 1 
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if self.pCurrent <= 0: 
self.pCurrent = 0 





self.prevB['state'] = DISABLED 

if cpane == self.panes - 1: 
self.nextB['text'] = 'Next' 
self.nextB['command'] = self.next 


self.pFrame[cpane] . forget () 
self.pFrame[self.pCurrent].pack(fill=BOTH, expand=YES) 


def done(self): 
#to be Overridden 
pass 


def __createInterface(self): 
self.__createWizardArea () 
self.__createSeparator () 
self.__createCommandArea () 
self.__createPanes () 
self.busyWidgets = ( self.root, ) 
self.createInterface() 


class TestWizardShell (WizardShell) : 
def createButtons (self): 
self.buttonAdd('Cancel', command=self.quit) O 
self.nextB = self.buttonAdd('Next', command=self.next) 
self.prevB = self.buttonAdd('Prev', command=self.prev, state=0) 


def createMain(self): 

self.wl = self.createcomponent('wl1', (), None, 
Label, (self.pInterior(0),), 
text='Wizard Area 1') 

self.wl.pack() 

self.w2 = self.createcomponent('w2', (), None, 
Label, (self.pInterior(1),), 
text='Wizard Area 2') 

self.w2.pack() 


def createInterface(self): 
WizardShell.createInterface(self) 
self.createButtons () 
self.createMain() 


def done(self): O 
print 'All Done' 


if _ name == '_ main_': 
test = TestWizardShel1l1 () 
test.run() 





Code comments 


@ WizardShell uses AppShell’s class variables, adding panes to define the number of discrete 
steps to be presented in the wizard. 


class WizardShell (Pmw.MegaWidget) : 
panes = 4 
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We initialize an empty pane for each step and initialize for the first step: 
self.pCurrent = 0 
self.pFrame = [None] * self.panes 

The main wizardArea is created: 


def _ createWizardArea (self): 
def _ createSeparator (self): 


def __createCommandArea(self): 


Then, a Separator and a CommandArea are added. 


buttonadd is slightly more comprehensive than AppShell’s since we have to enable and dis- 
able the next and prev buttons as we move through the sequence: 


def buttonAdd(self, buttonName, command=None, state=1): 
frame = Frame(self.__commandFrame) 
newBtn = Button(frame, text=buttonName, command=command) 
newBtn. pack () 
newBtn['state'] = [DISABLED, NORMAL] [state] 
frame.pack(side=RIGHT, ipadx=5, ipady=5) 
return newBtn 


Now we create a pane for each step, packing the current frame and forgetting all others so that 
they are not displayed: 


def __createPanes(self): 
for i in range(self.panes) : 
self.pFrame[i] = self.createcomponent('pframe',(), None, 
Frame, (self.interior(),), 
relief=FLAT, bd=1) 
if not i == self.pCurrent: 
self.pFrame[i] . forget () 
else: 
self.pFrame[i].pack(fill=BOTH, expand=YES) 


Similar to the convention to define an interior method, we define the pInterior method 
to give access to individual panes in the wizard: 
def pInterior(self, idx): 
return self.pFrame [idx] 
The next and prev methods forget the current pane and pack the next pane, changing the 
state of buttons as appropriate and changing the labels as necessary: 


def next(self): 
cpane = self.pCurrent 
self.pCurrent = self.pCurrent + 1 
self.prevB['state'] = NORMAL 


if self.pCurrent == self.panes - 1: 
self.nextB['text'] = 'Finish' 
self.nextB['command'] = self.done 


self.pFrame[cpane] . forget () 
self.pFrame[self.pCurrent].pack(fill=BOTH, expand=YES) 


Unlike AppShell, we have to store references to the control buttons so that we can manipulate 
their state and labels: 
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class TestWizardShell (WizardShell): 
def createButtons (self): 
self.buttonAdd('Cancel', command=self.quit) 
self.nextB = self.buttonAdd('Next', command=self.next) 
self.prevB = self.buttonAdd('Prev', command=self.prev, state=0) 


© The done method is clearly intended to be overridden! 


def done(self): 
print 'All Done' 





Generic Wizard Frame 





Figure 8.12 Wizard 


If you run wizardshell.py, you'll see the basic shell shown in figure 8.12. Now we need 
to populate the wizard. Here is an example installation sequence: 


Example_8_11.py 


from Tkinter import * 
import Pmw 

import sys, string 
import WizardShell 


class Installer (WizardShell.WizardShell): 
wizname = 'Install Widgets' 
panes= 4 


def createButtons (self): 
self.buttonAdd('Cancel', command=self.quit, state=1) 
self.nextB = self.buttonAdd('Next', command=self.next, state=1) 
self.prevB = self.buttonAdd('Prev', command=self.prev, state=0) 


def createTitle(self, idx, title): 0 
label = self.createcomponent('1%d' % idx, (), None, 
Label, (self.pInterior(idx),), 
text=title, 
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font=('verdana', 18, 'bold', ‘italic')) 
label .pack() 
return label 





def createExplanation(self, idx): O 
text = self.createcomponent ('t%d' % idx, (), None, 
Text, (self.pInterior(idx),), 
bd=0, wrap=WORD, height=6) 
fd = open('install%d.txt' % (idx+1) ) 
text.insert (END, fd.read() ) 
fd.close() 
text .pack (pady=15) 





def createPanelOne(self): 
self.createTitle(0, 'Welcome!') 
self.createExplanation (0) 


def createPanelTwo (self): © 
self.createTitle(1, 'Select Destination\nDirectory' ) 
self.createExplanation (1) 
frame = Frame(self.pInterior(1), bd=2, relief=GROOVE) 
self.entry = Label(frame, text='C:\\Widgets\\WidgetStorage', 

font=('Verdana', 10)) 

self.entry.pack(side=LEFT, padx=10) 
self.btn = Button(frame, text='Browse...') 
self.btn.pack(side=LEFT, ipadx=5, padx=5, pady=5) 
frame.pack() 











def createPanelThree(self): 
self.createTitle(2, 'Select Components') 
self.createExplanation (2) 
frame = Frame(self.pInterior(2), bd=0) 








idx = 0 
for label, size in [('Monkey','526k'), ('Aardvark','356k'), 
('Warthog','625k'), 
('Reticulated Python', '432k')]: 
ck = Checkbutton(frame) .grid(row=idx, column=0) 
lbl = Label(frame, text=label) .grid(row=idx, column=1, 
columnspan=4, sticky=W) 
siz = Label(frame, text=size) .grid(row=idx, column=5) 


idx = idx + 1 
frame.pack() 


def createPanelFour (self): 
self.createTitle(3, 'Finish Installation') 
self.createExplanation (3) 





def createInterface(self): 
WizardShell.WizardShell.createInterface (self) 
self.createButtons () 
self.createPanelOne() 
self .createPanelTwo () 
self.createPanelThree() 
self.createPanelFour () 


def done (self) : (4) 
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print 'This is where the work starts!' 


if _ name == '_main_': 
install = Installer() 
install.run() 





Code comments 


@ We begin by defining some routines to perform common tasks. Each of the wizard panes has 


a title: 
def createTitle(self, idx, title): 
label = self.createcomponent('1%d' % idx, (), None, 
Label, (self.pInterior(idx),), 
text=title, 
font=('verdana', 18, 'bold', ‘italic')) 
label .pack () 


return label 


@ Wizards need to supply concise and clear directions to the user; this routine formats the infor- 
mation appropriately using a regular Tkinter Text widget—the text is read from a file: 


def createExplanation(self, idx): 

text = self.createcomponent ('t%d' % idx, (), None, 
Text, (self.pInterior(idx),), 
bd=0, wrap=WORD, height=6) 

fd = open('install%d.txt' % (idx+1) ) 

text.insert (END, fd.read() ) 

fd.close() 

text .pack (pady=15) 


© Each pane in the wizard is constructed separately—here is an example: 


def createPanelTwo(self): 
self.createTitle(1, 'Select Destination\nDirectory' ) 
self.createExplanation (1) 
frame = Frame(self.pInterior(1), bd=2, relief=GROOVE) 
self.entry = Label(frame, text='C:\\Widgets\\WidgetStorage', 

font=('Verdana', 10) ) 

self.entry.pack(side=LEFT, padx=10) 
self.btn = Button(frame, text='Browse...') 
self.btn.pack(side=LEFT, ipadx=5, padx=5, pady=5) 
frame.pack() 





© This example is still a bit of a cheat because the done function still does not do very much! 
(However, I’m sure that you've got the idea by now!) 


Figure 8.13 shows the sequence supported by the wizard. Screens such as these will clearly 
give a polished image for an installation program. 
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Figure 8.13 An installation wizard 


8.7 Image maps 


The final topic in this chapter presents an input technique which is typically used with web 
pages; image maps associate actions with clickable areas on an image. You could argue that 
this topic belongs in “Panels and machines” on page 199, but I am including it here since it is 
a viable method for getting input from the user. 

If you take a look at “Building an application” on page 18 again, you will remember how 
a simple calculator was constructed using button widgets to bind user input to calculator 
functions. The application could be reworked using an image map; the major motivation for 
this would be to increase the realism of the interface by presenting an image of the calculator 
rather than a drawing. 

One of the problems of creating image maps is that without a tool to define the targets for 
the map, it can be a time-consuming task to measure and input all of the coordinates. Take a 
look at figure 8.14. The area around each of the buttons (the targets for this case) have been out- 
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Figure 8.14 Coordinate system for an image map 


lined in gray. The enlarged section shows the arrow keys in a little more detail. For each target, 
we need to determine the x-y coordinate of the top-left-hand corner and the x-y coordinate of 
the bottom-right-hand corner; together they define the rectangular area containing the button. 

The next example demonstrates how a simple tool can be constructed to first collect the 
coordinates of rectangular areas on an image, and then to generate a simple program to test 
the image map. This example supports only rectangular targets; you may wish to extend it to 
support polygonal and other target shapes. 


Example_8_12.py 


from Tkinter import * 
import sys, string 
class MakeImageMap: 


def __init__(self, master, file=None) : 
self.root = master 
self.root.title("Create Image Map") 
self.rubberbandBox = None 
self.coordinatedata = [] 
self.file = file 


self.img = PhotoImage(file=file) 
self.width = self.img.width() 
self.height = self.img.height() 


self.canvas = Canvas(self.root, width=self.width, 
height=self.height) 

self.canvas.pack(side=TOP, f£i11=BOTH, expand=0) 

self.canvas.create_image(0,0,anchor=NW, image=self.img) 


self.framel = Frame(self.root, bd=2, relief=RAISED) 
self.framel.pack(f£i11=xX) 
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IMAGE MAPS 


self.reference = Entry(self.framel, width=12) 

self.reference.pack(side=LEFT, fill=X, expand=1) 

self.add = Button(self.framel, text='Add', command=self.addMap) 

self.add.pack(side=RIGHT, fill=NONE, expand=0) 

self.frame2 = Frame(self.root, bd=2, relief=RAISED) 

self.frame2.pack(fi11=xX) 

self.done = Button(self.frame2, text='Build ImageMap', 
command=self.buildMap) 

self.done.pack(side=TOP, fill=NONE, expand=0) @ 





Widget.bind(self.canvas, "<Button-1>", self.mouseDown) 
Widget .bind(self.canvas, "<Buttonl-Motion>", self.mouseMotion) 
Widget .bind(self.canvas, "<Buttonl-ButtonRelease>", self.mouseUp) 


def mouseDown(self, event): © 
self.startx = self.canvas.canvasx(event.x) 
self.starty = self.canvas.canvasy(event.y) 


def mouseMotion(self, event): O 
x = self.canvas.canvasx(event.x) 
y = self.canvas.canvasy(event.y) 


if (self.startx != event.x) and (self.starty != event.y) 
self.canvas.delete(self.rubberbandBox) 
self.rubberbandBox = self.canvas.create_rectangle ( 
self.startx, self.starty, x, y, outline='white',width=2) 
self.root.update_idletasks () O 
O 


def mouseUp(self, event): 
self.endx = self.canvas.canvasx(event.x) 
self.endy = self.canvas.canvasy(event.y) 
self.reference. focus_set () 
self.reference.selection_range(0, END) 


def addMap (self): Q 
self.coordinatedata.append(self.reference.get(), 
self.startx, self.starty, 
self.endx, self.endy) 


def buildMap(self): 
filename = os.path.splitext(self.file) [0] 
ofd = open('%s.py' % filename, 'w') 
ifd = open('imagel.inp') (9) 
lines = ifd.read() 
ifd.close() 
ofd.write(lines) 


for ref, sx,sy, ex,ey in self.coordinatedata: 


ofd.write(" self.iMap.addRegion(((%5.1£,%5.1f)," 
"($5.1£,%5.1f£)), '%s')\n" % (sx,sy, ex,ey, ref)) 
ofd.write('\n%s\n' % ('#'*70)) D 
ofd.write('if _name__ == "__main__":\n') 


ofd.write(' root.title("%s")\n' % self.file) 


( 
( 
ofd.write(' root = Tk()\n') 
( 
ofd.write(' imageTest = ImageTest (root, width=%d, height=%d, ' 
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'file="$s")\n' % (self.width, self.height, self.file) ) 
ofd.write(' imageTest.root.mainloop()\n') 
ofd.close() 
self.root.quit() 


if _ name == '_main_': 
file = sys.argv[1] 
root = Tk() 


makeImageMap = MakeImageMap(root, file=file) 
makeImageMap. root .mainloop() 





Code comments 


The first task is to determine the size of the image to be mapped. Since we want to display the 
image on a canvas, we cannot just load the image, because the canvas will not resize to fit the 
image. Therefore, get the size of the image and size the canvas appropriately: 

self.img = PhotoImage(file=file) 

self.width = self.img.width() 

self.height = self.img.height () 
Our tool implements a simple graphic selection rectangle to show the selected target area. We 
bind functions to mouse button press and release and also to mouse motion: 

Widget .bind(self.canvas, "<Button-1>", self.mouseDown) 

Widget .bind(self.canvas, "<Buttonl-Motion>", self.mouseMotion) 

Widget .bind(self.canvas, "<Buttonl-ButtonRelease>", self.mouseUp) 
mouseDown converts the x- and y-screen coordinates of the mouse button press to coordi- 
nates relative to the canvas, which corresponds to the image coordinates: 

def mouseDown(self, event): 

self.startx = self.canvas.canvasx(event.x) 

self.starty = self.canvas.canvasy(event.y) 
mouseMot ion continuously updates the size of the selection rectangle with the current coordinates: 


def mouseMotion(self, event): 
x = self.canvas.canvasx(event.x) 
y = self.canvas.canvasy(event.y) 


if (self.startx != event.x) and (self.starty != event.y) 
self.canvas.delete(self.rubberbandBox) 
self.rubberbandBox = self.canvas.create_rectangle ( 
self.startx, self.starty, x, y, outline='white',width=2) 
Each time we update the selection rectangle, we have to call update_idletasks to display the 
changes. Doing a drag operation such as this causes a flood of events as the mouse moves, so 
we need to make sure that the screen writes get done in a timely fashion: 


self.root.update_idletasks() 


When the mouse button is released, we convert the coordinates of the finishing location and 
set focus to the entry widget to collect the identity of the map: 


def mouseUp(self, event): 
self.endx = self.canvas.canvasx(event.x) 
self.endy = self.canvas.canvasy(event.y) 
self.reference. focus_set () 
self.reference.selection_range(0, END) 





CHAPTER 8 DIALOGS AND FORMS 











@ Once the map ID has been entered, clicking the Add button adds the ID and the map coordi- 
nates to the list of map entries: 
def addMap(self): 
self.coordinatedata.append(self.reference.get(), 
self.startx, self.starty, 
self.endx, self.endy) 


© When the Build button is pressed, we generate a Python file to test the image map: 
def buildMap(self): 
filename = os.path.splitext(self.file) [0] 
ofd = open('%s.py' % filename, 'w') 
© The first section of the code is boilerplate, so it can be read in from a file: 
ifd = open('imagel.inp', 'r') 
lines = ifd.readlines() 
ifd.close() 
ofd.writelines (lines) 
O Then we generate an entry for each map collected previously: 
for ref, sx,sy, ex,ey in self.coordinatedata: 
ofd.write(" self.iMap.addRegion(((%5.1£,%5.1f)," 
"($5.1£,%5.1f)), '%s')\n" % (sx,sy, ex,ey, ref) ) 
@ Finally, we add some code to launch the image map: 
"\n3s\n' % ('#'*70)) 
ofd.write('if _ name == "__main__":\n') 
ofd.write(' root = Tk()\n') 
(" 


ofd.write 


( 
ofd.write(' root.title("%s")\n' % self.file) 
ofd.write(' imageTest ImageTest (root, width=%d, height=%d, ' 
'file="%s")\n' % (self.width, self.height, self.file)) 
ofd.write(' imageTest.root.mainloop()\n') 
ofd.close() 
All you have to do is supply a GIF file and then drag the selection rectangle around each 

of the target regions. Give the region an identity and click the Add button. When you have 
identified all of the regions, click the Build button. 





No This example illustrates how Python can be used to generate code from input 

data. Python is so easy to use and debug that it can be a valuable tool in build- 
ing complex systems. If you take a little time to understand the structure of the target 
code, you can write a program to generate that code. Of course, this only works if you 
have to produce lots of replicated code segments, but it can save you a lot of time and 
effort! 
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Figure 8.15 Creating an image map 


Let’s take a quick look at the code generated by the tool. 


Calculator.py 


from Tkinter 


import * 


from imagemap import * 
class ImageTest: 


def hit(self, event): 


self. 


infoVar.set(self.iMap.getRegion(event.x, event.y) ) 


def __ init__(self, master, width=0, height=0, file=None) : 


self. 
self. 
self. 


self. 
self. 


self. 
self. 
self. 
self. 
self. 
self. 


self. 
self. 


root = master 
root.option_add('*font', ('verdana', 12, 'bold')) 
iMap = ImageMap () 


canvas = Canvas(self.root, width=width, height=height) 
canvas.pack(side="top", fill=BOTH, expand='no') 


img = PhotoImage(file=file) 
canvas.create_image(0,0,anchor=NW, image=self.img) 
canvas.bind('<Button-1>', self.hit) 

infoVar = StringVar() 

info = Entry(self.root, textvariable=self.infoVar) 
info.pack (f£i11=xX) 


iMap.addRegion((( 61.0,234.0),( 96.0,253.0)), 'mode') 
iMap.addRegion (((104.0,234.0), (135.0,250.0)), 'del') 
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self.iMap.addRegion((( 19.0,263.0),( 55.0,281.0)), '‘alpha') 


self.iMap.addRegion((( 63.0,263.0),( 96.0,281.0)), 'x-t-phi') 
self.iMap.addRegion(((105.0,263.0), (134.0,281.0)), '‘stat') 

# ----- Some lines removed for brevity--------------- 
self.iMap.addRegion((( 24.0,467.0),( 54.0,488.0)), ‘on') 
self.iMap.addRegion((( 64.0,468.0),( 97.0,486.0)), '0') 
self.iMap.addRegion(((104.0,469.0),(138.0,486.0)), '.') 
self.iMap.addRegion(((185.0,469.0), (220.0,491.0)), '‘enter') 

if _ name_ == "__main__": 

root = Tk 


() 
root.title("calculator.gif") 
imageTest = ImageTest (root, width=237, height=513,file="calculator.gif") 
imageTest.root.mainloop() 





It’s really quite simple. The image map uses the ImageMap class. This class can be readily 
extended to support regions other than rectangles: 


imagemap.py 


class Region: o 
def __init__(self, coords, ref): 
self.coords = coords 
self.ref = ref 


def inside(self, x, y): O 
isInside = 0 
if self.coords[0] [0] <= x <= self.coords[1] [0] and \ 
self.coords[0] [1] <= y <= self.coords[1] [1]: 
isInside = 1 
return isInside 


class ImageMap: 
def __init__(self): 
self.regions = [] 
self.cache = {} 


def addRegion(self, coords, ref): 
self.regions.append(Region(coords, ref) ) 


def getRegion(self, x, y): 
try: 
return self.cache[ (x,y) ] 
except KeyError: 





for region in self.regions: 
if region.inside(x, y) == 
self.cache[(x,y)] = region 
return region.ref 
return None 





Code comments 


@ The Region class provides a container for the target regions: 
class Region: 


def __init__(self, coords, ref): 
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self.coords = coords 
self.ref = ref 


Detecting when a button press occurs within a region is a simple test: 


def inside(self, x, y): 
isInside = 0 
if self.coords[0][0] <= x <= self.coords[1][0] and \ 
self.coords[0][1] <= y <= self.coords[1] [1]: 
isInside = 1 
return isInside 


When we attempt to find a region, we first look in the cache that is accumulated from previ- 
ous lookups: 
def getRegion(self, x, y): 
try: 
return self.cache[(x,y)] 


If it is not in the cache, we have to search each of the regions in turn; we cache the map if we 


find it: 


except KeyError: 
for region in self.regions: 
if region.inside(x, y) == 1: 
self.cache[(x,y)] = region 
return region.ref 


calculator.gif 


Figure 8.16 shows calculator.py in action. 


Se See ants 


8.8 Summary 


This chapter has covered several types of forms and dialogs, 
ranging from simple fill-in-the-blank dialogs through browsers 
and wizards to image-mapping techniques. I hope that you will 
find sufficient material here so you can create forms appropriate 
for your own applications. 
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Figure 8.16 Running 
calculator.py 
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Panels and machines 


9.1 Building a front panel 199 9.5 And now for a more complete 
9.2 Modularity 201 example 220 

9.3. Implementing the front panel 201 9.6 Virtual machines using 

9.4 GIF, BMP and overlays 215 POV-Ray 232 


9.7 Summary 236 


This chapter is where Tkinter gets to be FUN! (Maybe I should find a hobby!) Network 
management applications have set a standard for graphical formats; many hardware device 
manufacturers supply a software front-panel display showing the current state of LEDs, con- 
nectors and power supply voltages—anything that has a measurable value. In general, such 
devices are SNMP-capable, although other systems exist. This model may be extended to 
subjects which have no mechanical form—even database applications can have attractive 
interfaces. The examples presented in this chapter should be useful for an application devel- 
oper needing a framework for alternative user interfaces. 


Building a front panel 


Let’s construct a hypothetical piece of equipment. The task is to present a front-panel dis- 
play of a switching system (perhaps an ATM switch or a router) to an administrator. The 
display will show the current state of the interfaces, line cards, processors and other compo- 
nents. For the purposes of the example, we shall assume that the device is SNMP-capable 
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and that the code to poll the devices agent and to receive and process traps will be developed 
independently from the GUI. 

If this were not a hypothetical device, you would have either the equipment itself or some 
technical specifications for the device to work from. For this example, we can dream up almost 
anything! Figure 9.1 shows a line drawing for the equipment. The device has two power sup- 
plies, each with a power connector and an on/off switch along with an LED showing the status 
of the power supply (off, on or failed). There are nine empty card slots, which will be populated 
with a variety of cards, and there are passive decorations such as the air-intake screens and chas- 
sis-mounting screws. The card slots will be populated with a switch card, a processor card, an 
eight-port 10Base-T Ethernet card*, a four-port FDDI card}, a two-channel T3 access card 
and four high-speed serial cards. I’m not sure what this device is going to do, who will be con- 
figuring it, or who will be paying for it, but it should be fun conjuring it up! 
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Figure 9.1 Hypothetical router/switch chassis 




































The most widely installed Ethernet local area networks (LANs) use ordinary telephone twisted-pair 
wire. When used on Ethernet, this carrier medium is known as 10BASE-T. 10BASE-T supports Ether- 
net's 10 Mbps transmission speed. 


t FDDI is a standard for data transmission on fiber optic lines in a local area network that can extend in 
range up to 200 km (124 miles). 


The T-3 line, a variant of the T-carrier system introduced by the Bell System in the USA in the 1960s, 
provides 44.736 Mbps. It is commonly used by internet service providers (ISPs). 
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Each of the cards has LEDs, connectors and passive components such as buttons, card- 
pullers and locking screws. Sounds like a lot? It is not as difficult as it may seem, on first anal- 
ysis, and once the basic components have been built, you will observe a great deal of code reuse. 


9.2 Modularity 


In section 7.2 on page 129 we started to develop a class library of components such as LEDs, 
switches and other devices. In this chapter we are going to use an expanded library of indica- 
tors, connectors and panel devices. We will also make use of the built-in status methods of the 
composite widgets, which was only briefly noted in the previous examples. We will also intro- 
duce the topic of navigation in the GUI, (see “Navigation” on page 300) since our front panel 
should provide the administrator access to functionality bound to each of the graphical ele- 
ments on the panel. A good example of such a binding is to warp the user to the list of alarms 
associated with an LED on the display or a configuration screen to allow him to set opera- 
tional parameters for a selected port. 

If you look again at figure 9.1, it is possible to identify a number of graphical components 
that must be developed to build the front panel. Although the configuration of each of the 
cards has not been revealed at this point, there are some “future” requirements for components 
to be displayed on the card which drives the following list: 


1 A chassis consisting of the rack-mount extensions and base front panel along with pas- 
sive components such as mounting screws. 
2 Card slots which may be populated with a variety of cards. 


3 A number of cards consisting of LEDs, connectors and other active devices along with 
the card front to mount the devices and other passive components such as card pullers 


and labels. 
4 Power supply modules containing connectors, switches and LEDs. 
5 Passive components such as the air-intake screens and the logo. 
6 LEDs, connectors (J-45*, BNCt, FDDI}, J-25, J-50 and power) and power switches. 


9.3 Implementing the front panel 


Some preparation work needs to be done to convert the notional front panel to a working sys- 
tem. In particular, it is necessary to calculate the sizes of screen components based on some 
scaling factors, since the majority of panels are much larger than typical computer screens. As 
the reader will observe in the following example code, the author tends to work with relative 
positioning on a canvas. This is a somewhat more difficult approach to widget placement 





* J connectors are typically used for serial connections. The number of pins available for connection is 
indicated by the suffix of the connector. Common connectors are J-9, J-25, and J-50. 


+ A Bayonet Neil-Concelman (BNC) connector is a type of connector used to connect using coaxial 
cable. 


+ FDDI connectors are used to connect fiber-optic lines and to normally connect a pair of cables, one 
for reception and one for transmission. 
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when contrasted with using 
the pack or grid geometry man- 











Figure 9.2 Making router/switch chassis 
measurements 





agers. However, precise place- 
objects 
requires the precision of the 
place geometry manager. 

The approach I took to 


implement this panel was to 


ment 


of graphical 


take a drawing of the panel and 
to perform some basic mea- 
surements. In figure 9.2, lines 
have been drawn marking the 
key dimensions that are needed 
to recreate a graphic represen- 


tation. Making measurements on a drawing can be easier than performing the measurements 


ona real device. Overall width and height are measured in some standard units (such as inches 


or centimeters) and then the relative size of each of the rectangular objects and the relative off- 


set of one corner of the object must be calculated. The offset is used for the placer calls in the 


code. The selected corner is the anchor for this call. It may appear to be a lot of work, but it 


takes just a few minutes to get the required information. 


The example extends the class library to provide a number of new graphical elements; in 


the listings that follow, elements that have already been presented have been eliminated. 


Components_1.py 


from Tkinter import * 
from GUICommon import * 
from Common import * 


class Screen (GUICommon) : 
def _ init__(self, master, 


self.screen_frame = Frame(master, 


bg=bg, 
self.base = bg 


bd=0) 


self.set_colors(self.screen_frame) 
# radius of an air hole 
# spacing between holes 


radius = 4 
ssize = radius*3 


rows = int (height/ssize) 
cols = int(width/ssize) 


self.canvas = Canvas(self.screen_frame, 


bg=Color.PANEL, height=1, 





width=1): 
width=width, height=height, 


ò creating an 
instance 


height=height, width=width, 


bg=bg, bd=0, highlightthickness=0) 
self.canvas.pack(side=TOP, fi11=BOTH, expand=NO) 
y = ssize - radius# O Optimizing 
for r in range (rows): performance 
x0 = ssize -radius 
for c in range (cols): 
x = x0 + (ssize*c) 


CHAPTER 9 PANELS AND MACHINES 











self.canvas.create_oval (x-radius, 
x+radius, y+radius, 
fill=self.dbase, 
outline=self.lbase) 


y y + ssize 


class PowerConnector: 


def __init__(self, master, bg=Color.PANEL) : 




















y-radius, 





self.socket_frame = Frame(master, relief="raised", width=60, 
height=40, bg=bg, bd=4) 
inside=Frame(self.socket_frame, relief="sunken", width=56, 
height=36, bg=Color.INSIDE, bd=2) 
inside.place(relx=.5, rely=.5, anchor=CENTER) 
ground=Frame(inside, relief="raised", width=6, height=10, 
bg=Color.CHROME, bd=2) 
ground.place(relx=.5, rely=.3, anchor=CENTER) 
pl=Frame(inside, relief="raised", width=6, height=10, 
bg=Color.CHROME, bd=2) 
pl.place(relx=.25, rely=.7, anchor=CENTER 
p2=Frame(inside, relief="raised", width=6, height=10, 
bg=Color.CHROME, bd=2) 
p2.place(relx=.75, rely=.7, anchor=CENTER 
class PowerSwitch(GUICommon) : 
def __init__(self, master, label='I 0', base=Color. PANEL) : 

self.base = base Calculating 

self.set_colors (master) colors 

self.switch_frame = Frame(master, relief="raised", width=45, 

height=28, bg=self.vlbase, bd=4) 

switch = Frame(self.switch_frame, relief="sunken", width=32, 
height=22, bg=self.base, bd=2) 

switch.place(relx=0.5, rely=0.5, anchor=CENTER) 

lbl=Label (switch, text=label, font=("Verdana", 10, "bold"), 


fg='white', 
1lbl.place(relx=0.5, 


bd=0, 
rely=0.5, 


bg=self.dbase) 
anchor=CENTER) 


class PowerSupply (GUICommon) : 
def __init__(self, master, width=160, 
status=STATUS_ON) : 
self.base bg 
self.set_colors (master) 


height=130, 


self.psu_frame Frame (master, 


width=width, height=height) 














relief=SUNKEN, bg=self.dbase, 


bg=Color. PANEL, 


bd=2, 


Label (self.psu_frame, text='DC OK', fg='white', 
bg=self.dbase, font=('Verdana', 10, 'bold') ,bd=0) .place(relx=.8, 
rely=.15, anchor=CENTER) 
self.led = LED(self.psu_frame, height=12, width=12, shape=ROUND, 





bg=self.dbase) 
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self.led.led_frame.place(relx=0.8, rely=0.31, anchor=CENTER) 





lsub = Frame(self.psu_frame, width=width/1.2, height=height/2, 
bg=self.dbase, bd=1, relief=GROOVE) 


lsub.place(relx=0.5, rely=0.68, anchor=CENTER) 











pwr=PowerConnector (lsub) 

pwr.socket_frame.place(relx=0.30, rely=0.5, anchor=CENTER) 
sw=PowerSwitch (lsub) 

sw.switch_frame.place(relx=0.75, rely=0.5, anchor=CENTER) 




















class Screw(GUICommon) : 
def _ init__(self, master, diameter=18, base="gray40", bg=Color.PANEL) : 
self.base = base 





basesize = diameter+6 

self.screw_frame = Frame (master, relief="flat", bg=bg, bd=0, 
highlightthickness=0) 

self.set_colors (self.screw_frame) 


canvas=Canvas (self.screw_frame, width=basesize, height=basesize, 
highlightthickness=0, bg=bg, bd=0) 

center = basesize/2 

r = diameter/2 

r2 =r - 4.0 


canvas.create_oval(center-r, center-r, center+r, center+r, 
fill=self.base, outline=self.lbase) 

canvas.create_rectangle(center-r2, center-0.2, 

center+r2, center+0.2, 

fill=self.dbase, width=0) 
canvas.create_rectangle(center-0.2, center-r2, 

center+0.2, center+r2, 

fill=self.dbase, width=0) 
canvas.pack(side="top", fill='x', expand='no') 


class CardBlank (GUICommon) : 
def __init__(self, master=None, width=20, height=396, 
appearance="raised", bd=2, base=Color.CARD): 
self.base = base 
self.set_colors (master) 
self.card_frame=Frame(master, relief=appearance, height=height, 
width=width, bg=base, bd=bd) 


top_pull = CardPuller(self.card_frame, CARD_TOP, width=width) 
top_pull.puller_frame.place(relx=.5, rely=0, anchor=N) 


bottom_pull = CardPuller(self.card_frame, CARD_BOTTOM, width=width) 
bottom_pull.puller_frame.place(relx=.5, rely=1.0,anchor=S) 





Code comments 


@ In some ofthe earlier examples we used Tkinter’s internal reference to the instance of the wid- 
gets, so the following was possible: 





Button(parent, text=’OK’) .pack(side=LEFT) 
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The structure of the code for this example requires that we make sure that instances of 
objects are unique. Each widget must keep references to its child widgets. 


self.screen_frame = Frame(master, width=width, height=height, 
bg=bg, bd=0) 


This creates a specific instance of screen_frame within self. 


@ The air-intake screen illustrates the ease with which repeated graphical objects may be created. 
It also highlights the importance of careful code construction—it is easy to forget that Python 
is an interpreted language and it is important to ensure that code is constructed in a way that 
optimizes execution. 

y = ssize - radius 
for r in range(rows): 
x0 = ssize -radius 
for c in range(cols): 
x = x0 + (ssize*c) 
self.canvas.create_oval(x-radius, y-radius, 
x+radius, ytradius, 
fill=self.dbase, 
outline=self.lbase) 
y = y + ssize 
Some additional code might be appropriate here, since the first air intake is the “tall” by 
“narrow” case, but the lower intake has an opposite aspect. The loop could be improved by 
having the outer loop iterate over largest dimension to reduce some of the math operations in 
the inner loop. Of course, this would increase the code complexity and for many operations 
might be unnecessary, but is worth considering. Remember that a good C or C++ would opti- 
mize loops for you; you are Python’s optimizer! 


© curtcommon.set_colors has been extended to pass a widget to provide access to winfo 
early in the initializer. 


def _ init_ (self, master, label='I 0', base=Color.PANEL): 
self.base = base 
self.set_colors (master) 


In this case, the master container widget and base color have been passed in the con- 
structor and are used to set the color variants for the object. 


Components_1.py (continued) 


class CardPuller (GUICommon) : 


def __init__(self, master, torb, width=20): 
self.base = master['background' ] 
self.set_colors (master) O 
self.puller_frame=Frame (master, width=width, height=32, 
bg=self.lbase, relief='flat') 


Frame(self.puller_frame, width=width/8, height=8, 
bg=self.dbase) .place(relx=1.0, rely=[1.0,0] [torb], O 
anchor=[SE,NE] [torb] ) 











Frame(self.puller_frame, width=width/3, height=24, 
bg=self.vdbase) .place(relx=1.0, rely=[0,1.0][torb], 
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anchor=[NE, SE] [torb] ) 


Screw(self.puller_frame, diameter=10, base=self.base, 
bg=self.lbase) .screw_frame.place(relx=0.3, rely=[0.2,0.8][torb], 
anchor=CENTER) 





class Chassis: 
def __init__(self, master): 
self.outer=Frame(master, width=540, height=650, 
borderwidth=2, bg=Color. PANEL) 
self.outer. forget () O 


self.inner=Frame (self.outer, width=490, height=650, 
borderwidth=2, relief=RAISED, bg=Color.PANEL) 
self.inner.place(relx=0.5, rely=0.5, anchor=CENTER) 

















self.rack = Frame(self.inner, bd=2, width=325, height=416, 
bg=Color.CHASSIS) 
self.rack.place(relx=0.985, rely=0.853, anchor=SE 





Aner = 3257/9 
x = 0.0 o Creating blank cards 
for i in range(9): 
card =CardBlank(self.rack, width=incr-1, height=414) 
card.card_frame.place(x=x, y=0, anchor=NW) 
x = x + incr 


self.img = PhotoImage(file='images/logo.gif') 
self.logo=Label(self.outer, image=self.img, bd=0) 
self.logo.place(relx=0.055, rely=0.992, anchor=SW) 


for x in [0.02, 0.98]: 
for y in [0.0444, 0.3111, 0.6555, 0.9711]: 
screw = Screw(self.outer, base="gray50") 
screw.screw_frame.place(relx=x, rely=y, anchor=CENTER) 











self.psul = PowerSupply(self.inner) 
self.psul.psu_frame.place(relx=0.99, rely=0.004, anchor=N 
self.psu2 = PowerSupply(self.inner) 
self.psu2.psu_frame.place(relx=0.65, rely=0.004, anchor=N 


GI 





GI 


self .psu2.led.turnoff () © Deactivating LED 


screenl = Screen(self.inner, width=150, height=600, bg=Color. PANEL) 
screenl.screen_frame.place(relx=0.16, rely=0.475, anchor=CENTER) 


screen2 = Screen(self.inner, width=330, height=80, bg=Color. PANEL 


screen2.screen_frame.place(relx=0.988, rely=0.989, anchor=SE) 





























Code comments (continued) 


© In the cardpuller class we obtain the base color from the parent widget, rather than passing 
it in the constructor. 


def _ init_ (self, master, torb, width=20): 
self.base = master['background' ] 
self.set_colors (master) 
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@ We index into a list to obtain the y-coordinate and the anchor-position for the place call. 
This valuable technique is used in many examples throughout the book. 
bg=self.dbase) .place(relx=1.0, rely=[1.0,0] [torb], 
anchor=[SE,NE] [torb] ) 
© If widgets are created in a complex GUI, there can be some somewhat ugly effects to the dis- 
play if the window is realized. One of these effects is that with the pack or grid geometry man- 
agers, the widgets are readjusted several times as additional widgets are created. Another effect 
is that it takes longer to draw the widgets, since the system redraws the widgets several times as 
widget configurations change. The solution is to delay the realization of the outer container of 
the widget hierarchy: 


self.outer. forget () 


@ The loop populates the card rack with blank cards: 
incr = 325/9 
x = 0.0 
for i in range(9): 
card =CardBlank(self.rack, width=incr-1, height=414) 
card.card_frame.place(x=x, y=0, anchor=NW) 
x= X + incr 


© Finally, we change the state of one of the LEDs on the display. You'll learn more about this 
later. 
self.psu2.led.turnoff () 


Since the front panel will be built incrementally, for the purpose of illustration, a sepa- 
rate module, FrontPanel_1.py, is used to create the device. 


FrontPanel.py 


#! /bin/env/python 


from Tkinter import * 
from Components_1 import * 
from GUICommon import * 
from Common import * 


class Router (Frame): 
def __init__(self, master=None) : 
Frame.__init__(self, master) 
Pack.config(self) 
self.createChassis() 


def createChassis(self): 
self.chassis = Chassis(self) 
# Realize the outer frame (which 
# was forgotten when created) 
self.chassis.outer.pack (expand=0) 1) Realize the frame 


if _ name == '_main_': 
root = Router () 
root.master.title("CisForTron") 
root.master.iconname("CisForTron") 
root.mainloop () 
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Code comments 


If you examine the __init__ method for each of the frames in the various classes in 
Components_l.py, you will notice that there are no geometry-management calls. It would 
have been possible to pass the location to place the object or simply pack the object within the 
constructor, but the style of coding used here allows the user to have more control over widget 
geometry. This is especially true for the chassis frame; this widget was explicitly forgotten so 
that the screen updates are made before the chassis is realized. This improves performance 
considerably when a large number of graphic objects need to be drawn. 
self.chassis.outer.pack (expand=0) 

Here, the chassis frame is packed, realizing the widget and drawing the contained wid- 

gets. It does make a difference! 


When FrontPanel.py is run, the screen shown in figure 9.3 is displayed. This display 
draws remarkably fast, even though we have to construct each of the air-screen holes individ- 
ually. For highly computational or memory-intensive graphics which depict purely passive 
components, it is probably better to use GIF or bitmap images. Some aspects of this are dis- 
cussed in “GIF, BMP and overlays” on page 215. Notice how we use the intrinsic three-dimen- 
sional properties of the widgets to create some depth in the display. In general, it is best to avoid 
trying to totally mimic the actual device and produce some level of abstraction. 

Let’s create one of the cards that will populate the chassis. The T3 Access card has four 
BNC connectors (two pairs of Rx/Tx connectors), four LEDs for each pair of BNC connectors, 
and some identifying labels. Every card in the chassis has a power (PWR) and fault (FLT) LED. 


Figure 9.3 Basic router chassis 
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Here is the code to construct a BNC connector: 


Components.py (fragment) 


class BNC (GUICommon) : 0 
def __init__(self, master, status=0, diameter=18, 
port=-1, fid=''): 


self.base = master['background' ] 

self.hitID = fid 

self.status=status 

self.blink = 0 

self.blinkrate = 1 

self.on = 0 

self.onState = None 

self.Colors = [None, Color.CHROME, Color.ON, 


Color.WARN, Color.ALARM, '#00ffdd'] 


basesize = diameter+6 





self.bnc_frame = Frame(master, relief="flat", bg=self.base, 
bd=0, highlightthickness=0, takefocus=1) 
self.bnc_frame.pack (expand=0) 
self.bnc_frame.bind('<FocusIn>', self.focus_in) 9 
self.bnc_frame.bind('<FocusOut>!', self.focus_out) 


self.canvas=Canvas(self.bnc_frame, width=basesize, 
height=basesize, highlightthickness=0, 
bg=self.base, bd=0) 
center = basesize/2 
r = diameter/2 
self.pins=self.canvas.create_rectangle(0, center+2, basesize-1, 
10, £111=Color.CHROME) 
self .bnc=self.canvas.create_oval(center-r, center-r, 
center+r, center+r, 
£i11=Color.CHROME 
outline="black") 





r= r-3 

self.canvas.create_oval(center-r, center-r, center+r, center+r, 
fill=Color.INSIDE, outline='black') 

r= r-2 

self.canvas.create_oval(center-r, center-r, center+r, center+r, 
£i11=Color.CHROME) 

r = r-3 

self.canvas.create_oval(center-r, center-r, center+r, center+r, 
£il1l=Color.INSIDE, outline='black') 





self.canvas.pack(side=TOP, fi11=X, expand=0) 
if self.hitID: 
self.hitID = '%s.%d' % (self.hitID, port) 
for widget in [self.bnc_frame]: 
widget .bind('<KeyPress-space>', self.panelMenu) 
widget .bind('<Button-1>', self.panelMenu) 
for widget in [self.canvas]: 
widget .bind('<1>', self.panelMenu) 


def focus_in(self, event): 
self.last_bg= self.canvas.itemcget(self.bnc, 'fill') 
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self.canvas.itemconfig(self.bnc, f£i11=Color.HIGHLIGHT) 
self.update() 


def focus_out(self, event): 
self.canvas.itemconfig(self.bnc, fill=self.last_bg) 
self.update() 


def update(self): © 
# First do the blink, if set to blink 
if self.blink: 
if self.on: 
if not self.onState: 
self.onState self.status 
self.status = STATUS_OFF 
self.on =0 
else: 
if self.onState: 
self.status = self.onState # Current ON color 
self.on = 1 
# now update the status 
self.canvas.itemconfig(self.bnc, fill=self.Colors[self.status] ) 
self.canvas.itemconfig(self.pins, fill=self.Colors[self.status] ) 
self.bnc_frame.update_idletasks () 
if self.blink: 
self.bnc_frame.after(self.blinkrate * 1000, self.update) 


I 





Code comments 


@ This example uses the GUICommon mixin class to define basic methods for widget state 
manipulation. 
class BNC (GUICommon) : 


@ Here we bind callbacks to FocusIn and FocusOut events. 


self.bnc_frame.bind('<FocusIn>', self.focus_in) 
self.bnc_frame.bind('<FocusOut>', self.focus_out) 


This binds the focus_in and focus_out functions to the widget so that if we tab into 
the widget or click the widget, we highlight it and enable the functions to be accessed. 


© All of the graphical objects (LEDs, BNC, J and FDDI connectors) define a specific update 
method to change the appearance of the widget based upon current status. We need special- 
ized methods to allow us to update the color of particular areas within the composite. This 
method is also responsible for blinking the widget at one-second intervals. 


def update(self): 
# First do the blink, if set to blink 
if self.blink: 
if self.on: 
if not self.onState: 
self.onState = self.status 
self.status = STATUS_OFF 
self.on =0 
else: 
if self.onState: 
self.status = self.onState # Current ON color 
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self.on = 1 
# now update the status 
self.canvas.itemconfig(self.bnc, fill=self.Colors[self.status] ) 
self.canvas.itemconfig(self.pins, fill=self.Colors[self.status] ) 
self.bnc_frame.update_idletasks () 
if self.blink: 
self.bnc_frame.after(self.blinkrate * 1000, self.update) 


Now, we complete the example by defining the layout of the T3 Access card: 


class StandardLEDs (GUICommon) : O 
def __init__ (self, master=None, bg=Color.CARD) : 
for led, label, xpos, ypos, state in [('flt', 'Flt', 0.3, 0.88, 1), 
('‘pwr', 'Pwr', 0.7, 0.88, 2)]: 
setattr (self, led, LED(self.card_frame, shape=ROUND,width=8, 
status=state, bg=bg) ) 
getattr(self, led) .led_frame.place(relx=xpos,rely=ypos, 
anchor=CENTER) 
Label (self.card_frame,text=label, font=("verdana", 4), 
fg="white",bg=bg) .place (relx=xpos, rely=(ypos+0.028), 
anchor=CENTER) 

















class T3AccessCard(CardBlank, StandardLEDs) : O 
def _ init_ (self, master, width=1, height=1): 
CardBlank.__init__(self, master=master, width=width, height=height) 
bg=master['background' ] 
StandardLEDs.__ init__(self, master=master, bg=bg) 
for port, lbl, tag, ypos in [ (1, 'RX1', 'T3AccessRX', 0.3 
(2,'TX1', 'T3AccessTX', 0.4 
(3, 'RX2', 'T3AccessRX', 0.6 
(4,'TX2', 'T3AccessRX', 0.7 








setattr(self, ‘bnc%d’ % port, BNC(self.card_frame, 
fid=tag,port=port) ) 
getattr(self, ‘bnc%d’ % port) .bnc_frame.place(relx=0.5, 
rely=ypos, anchor=CENTER) ) 
Label (self.card_frame,text=lbl, 
font=("verdana", 6), fg="white", 
bg=bg) .place(relx=0.5,rely=(ypos+0.045) , anchor=CENTER) 


for led, 1bl, xpos, ypos, state in [('rxc','RXC',0.3,0.18,2) 


[ 

('oos','OOS',0.7,0.18,1) 
('flt','FLT',0.3,0.23,1) 
('syn', 'SYN',0.7,0.23,2) 
(Sexe SRC, 0.35 '0..53:-:2)) 
('oos','OOS',0.7,0.53,1) 
('f£1t', 'FLT',0.3,0.58,1) 


('syn', 'SYN',0.7,0.58,2)]: 
setattr (self, led, LED(self.card_frame, shape=ROUND,width=8, 
status=state, bg=bg) ) 
getattr(self, led) .led_frame.place(relx=xpos,rely=ypos, 
anchor=CENTER) 





Label (self.card_frame,text=lbl, 
font=("verdana", 4), fg="white", 
bg=bg) .place(relx=xpos,rely=(ypos+0.028) , anchor=CENTER) 
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Code comments 


@ We add one class to draw the LEDs that appear on each card in the rack: 
class StandardLEDs (GUICommon) : 


@ The T3 access card inherits from the CardBlank and StandardLEDs classes which are explic- 
itly constructed: 
class T3AccessCard(CardBlank, StandardLEDs) : 
def __ init__(self, master, width=1, height=1): 
CardBlank.__init__(self, master=master, width=width, 
height=height) bg=master['background' ] 
StandardLEDs.__ init__(self, master=master, bg=bg) 
© Readers who have been observing my coding style will have noticed a definite pattern; I like to 
create objects from lists of tuples! This example is no exception: 
for port, lbl, tag, ypos in [ (1, '!RX1', 'T3AccessRX', 0.30) 
2,'TX1', 'T3AccessTX', 0.40), 
3,'RX2','T3AccessRX', 0.65), 
4,'TX2','T3AccessRX', 0.75)]: 


Python’s ability to unpack a tuple contained in a list of tuples provides a mechanism to 
compress the amount of code required to achieve a desired effect. 


© The arguments unpacked from the tuple are substituted in setattr and getattr calls: 
setattr(self, ‘bnc%d’ % port, BNC(self.card_frame, 
fid=tag,port=port) ) 
getattr(self, ‘bnc%d’ % port) .bnc_frame.place(relx=0.5, 
rely=ypos, anchor=CENTER) ) 
Label (self.card_frame,text=l1bl, 
font=("verdana", 6), fg="white", 
bg=bg) .place(relx=0.5,rely=(ypos+0.045) ,anchor=CENTER) | 











This style of coding results in tight code. It may be a little difficult to read initially, but it 
is still an efficient way of creating graphic elements in a loop. 


As the last step to adding the T3 card, we must modify the loop that generates blank cards 
to add one of the T3 Access cards: 


for i in range(9): 
if a == 
card =T3AccessCard(self.rack, width=incr-1, height=414) 
else: 
card =CardBlank(self.rack, width=incr-1, height=414) 
card.card_frame.place(x=x, y=0, anchor=NW) 
x = x + incr 
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Figure 9.5 Populated chassis 
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Figure 9.4 
T3 access card 


Running FrontPanel2.py will display the 
screen shown in figure 9.4. The next step is a little 
scary. Creating the additional graphic elements and 
placing them on the cards does not require a lot of 
code. The code will not be presented here, it may 
be obtained online. If you run FrontPanel_3.py, 
you will see the screen in figure 9.5. 

A few more words of explanation about the 
code presented earlier: We are attaching a menu 
operation to the widget. Access to the menu will be 
from the keyboard, using the spacebar or by click- 
ing with the mouse. 
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if self.hitID: 
self.hitID = '%s.%d' % (self.hitID, port) 
for widget in [self.bnc_frame]: 
widget .bind('<KeyPress-space>', self.panelMenu) 
widget.bind('<Button-1>', self.panelMenu) 
for widget in [self.canvas]: 
widget.bind('<1>', self.panelMenu) 


We define the focus_in and focus_out methods. 


def focus_in(self, event): 
self.last_bg= self.canvas.itemcget(self.bnc, 'fill') 
self.canvas.itemconfig(self.bnc, fi11=Color.HIGHLIGHT) 
self.update() 


def focus_out(self, event): 
self.canvas.itemconfig(self.bnc, fill=self.last_bg) 
self.update() 


The purpose of these methods is to change the high- 
light color of the widgets as we either click on them with 
the mouse or navigate to them using the tab key. As we 
navigate from widget to widget, we display a highlight to 
show the user where the focus is. Figure 9.6 shows the 
effect of tabbing through the field. Although it’s less obvi- 
ous without color, the selected connector is blue; in con- 
trast, the other connectors are gray. 

This method of navigation is somewhat alien to users 
who have been conditioned to using the mouse to navigate 
GUIs. However, the ability to select tiny graphic objects 
Figure 9.6 Widget focus is valuable and it can change a user’s opinion of a product 





markedly. Without naming names, I have seen network 
management systems which required the user to click on graphic elements no more than 2mm 
square! 
Components_3.py contains some additional code to animate the display to show the 
effect of status changes. Basically, each class that defines objects which can display status 
appends the instance to a widget list: 


st_wid.append (self) # register for animation 

We then bind the animate function to the logo: 
self.img = PhotoImage(file='logo.gif') 
self.logo=Label(self.outer, image=self.img, bd=0) 
self.logo.place(relx=0.055, rely=0.992, anchor=SW) 
self.logo.bind('<Button-1>', self.animate) 

The animate function is quite simple: 

def animate(self, event): 


import random 
choice = random.choice(range(0, len(st_wid)-1) ) 
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op = random.choice(range(0, len(ops)-1)) 


pstr = 'st_wid[%d].%s()' % (choice, ops[op]) 
self.cobj = compile(pstr, 'inline', 'exec') 
self.rack.after(50, self.doit) 


def doit(self): 
exec (self.cobj) 
self.rack.after(50, self.animate (None) ) 


If you run FrontPanel_3.py and click on the 
logo, you will activate the animation. Of course, 
it is difficult to depict the result of this in a black- 
and-white printed image, but you should be able 
to discern differences in the shading of the con- 
trols on the panels—especially the J45 connectors 
on the fourth panel from the left in figure 9.7. 

Of course, there is quite a lot of work to 
turn a panel such as this into a functional system. 
You would probably use a periodic SNMP poll of 
the device to get the state of each of the compo- 
nents and set the LEDs appropriately. In addi- 
tion, you might monitor the content of the card 
rack to detect changes in hardware, if the device 
supports “hot pull” cards. Finally, menus might 
be added to the ports to give access to configura- 
tion utilities. 





Figure 9.7 Animated widgets 


GIF, BMP and overlays 


The panels and machines introduced in the previous section used drawn interfaces. With a lit- 
tle effort, it is possible to produce a panel or machine that closely resembles the actual device. 
In some cases, it is necessary to have a little artistic flair to produce a satisfactory result, so an 
alternate approach must be used. Sometimes, it can be easier to use photographs of the device 
to produce a totally accurate representation of it; this is particularly true if the device is large. 
In this section I will provide you with a number of techniques to merge photographic images 
with GUIs. 

Let’s begin by taking a look at the front panel of the Cabletron SmartSwitch 6500 shown 
in figure 9.8. If you contrast the magnified section in this figure with the components in figure 
9.6, you may notice that the drawn panel shows clearer detail, particularly for text labels. How- 
ever, if you consider the amount of effort required to develop code to precisely place the com- 
ponents on the panels, the photo image is much easier. In addition, the photo image 
reproduces every detail, no matter how small or complex, and it has strong three-dimensional 
features which are time-consuming to recreate with drawn panels. 
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Photo courtesy Cabletron Systems 


The task of creating modular panels is somewhat easier than creating similar panels with 
drawn components. Constructing a system with images requires the following steps: 
1 Photograph the device with an empty card rack, if possible. 
Photograph the device with cards inserted (singly, if possible) at the same scale. 


Crop the card images so that they exactly define a card face. 


Aà Où N 


Create a class for each card type, loading appropriate graphics and overlays for active 
components (LEDs, annunciators, etc.) and navigable components (connectors, but- 
tons, etc.). 

5 Create a chassis population based on configuration. 


6 Write the rest of the supporting code. 


In the following code, just a sample of the code will be presented. The full source code 
may be obtained online. 


Components_4.py 


class C6C110_CardBlank (GUICommon) : 
def __ init__(self, master=None, width=10, height=10, 
appearance=FLAT, bd=0): 
self.card_frame=Frame(master, relief=appearance, height=height, 
width=width, bd=bd, highlightthickness=0) 


class C6C110_ENET(C6C110_CardBlank) : 
def __init__(self, master, slot=0): 
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self.img = PhotoImage(file='images/6c110_enet.gif') 
setattr(glb, ‘img%d % slot, self.img) 

self.width = self.img.width() 

self.height = self.img.height () 


C6C110_CardBlank.__init__(self, master=master, width=self.width, 
height=self.height) 


xypos = [(10,180), (10,187), 
(10,195), (10,203), LED Positions 
(10,210), (10,235), 
(10,242) ] 


bd=0,highlightthickness=0, 
height=self.height, selectborderwidth=0) 
self.canvas.pack(side="top", f£i11=BOTH, expand='no') 
self.canvas.create_image(0,0,anchor=NW, 
image=eval ('glb.img%d' % slot) ) 


self.canvas = Canvas(self.card_frame, width=self.width, -o 


© 


for i, y in [(0, 0.330), (1, 0.619)]: 
setattr(self, 'j%d' % i, Enetl0baseT(self.card_frame, 
fid="10Base-T-%d" % i, port=i, orient=HW_LEFT, 
status=STATUS_OFF, xwidth=15, xheight=12) ) 
getattr(self, 'j%d' % i).j45 _frame.place(relx=0.52, 
rely=y, anchor=CENTER) 

















for i in range (len (xypos)): © Create LEDs 
xpos,ypos = xypos[i] 
setattr(self, 'led%d' % (i+1), CLED(self.card_frame, 
self.canvas, shape=ROUND, width=4, status=STATUS_ON, 
relx=xpos, rely=ypos) ) 


class C6C110_Chassis: 
def __init__(self, master): 
self.outer=Frame(master, borderwidth=0, bg=Color. PANEL) 
self.outer. forget () 


self.img = PhotoImage(file='images/6c110_chassis.gif') 
self.width = self.img.width() 
self.height = self.img.height () 


self.canvas = Canvas(self.outer, width=self.width, 
height=self.height, selectborderwidth=0) 

self.canvas.pack(side="top", f£i11=BOTH, expand='no') 

self.canvas.create_image(0,0,anchor=NW, image=self.img) 


self.rack = Frame(self.outer, bd=0, width=self.width-84, 
height=self.height-180, 
bg=Color.CHASSIS, highlightthickness=0) 
self.rack.place(relx=0.081, rely=0.117, anchor=Nw) 


x = 0.0 
for i in range(12): 
if 4. im 10, 1y2/3,4;5)s 
card =C6C110_FDDI(self.rack, slot=i) 
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elif i in [6,7,8,9]: 

card =C6C110_ENET(self.rack, slot=i) 
else: 

card =C6C110_PSU(self.rack, slot=i) 
card.card_frame.place(x=x, y=0, anchor=NW) 
x = xX + card.width 





Code comments 


Most of the code resembles that for drawn panel components. The code is a little shorter, 
since it is not necessary to build as many components. 

self.img = PhotoImage(file='images/6c110_enet.gif') 

setattr(glb, ‘img%d % slot, self.img) 

self.width = self.img.width() 

self.height = self.img.height() 

In the __init__ method, we create a PhotoImage instance. It is important that this 
reference remains within scope. If the image gets garbage-collected, you'll see an empty back- 
ground field where you had hoped to have an image. The size of the image is obtained (in pix- 
els) in order to construct the panels. 


As might be expected, we build a list of tuples to contain the calculated positions of the LEDs. 
xypos = [(10,180), (10,187), 


All borders, highlights, and selectionborders must be zero-width to ensure that the panels can 
be butted together. 
self.canvas = Canvas(self.card_frame, width=self.width, 
bd=0,highlightthickness=0, 
height=self.height,selectborderwidth=0) 


The image is created on the base canvas using the stored PhotoImage. 


self.canvas.create_image(0,0,anchor=NwW, 


o 


image=eval ('glb.img%d' % slot)) 


The J45 connectors are drawn over the connectors depicted in the image; this adds navigation 
and status properties to the otherwise passive devices. 
for i, y in [(0, 0.330), (1, 0.619)]: 
setattr(self, 'j%d' % i, Enet10baseT(self.card_frame, 
fid="10Base-T-%d" % i, port=i, orient=HW_LEFT, 
status=STATUS_OFF, xwidth=15, xheight=12) ) 
getattr (self, 'j%d' % i).j45_frame.place(relx=0.52, 
rely=y, anchor=CENTER) 








The size of the connector is passed in the constructor; this adds functionality to the J45 
connectors shown earlier in the chapter. 


The LEDs are drawn on the canvas at their designated location. Note that these use the 

CLED class, not the LED class, because these LEDs are drawn directly on the canvas and not 

within a Frame. If the LED class had been used, we would have experienced problems in 

attempting to fill the rectangular frame associated with the widget and the background color. 
for i in range(len(xypos)): 


xpos, ypos = xypos[il] 
setattr (self, 'led%d' % (i+1), CLED(self.card_frame, 
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self.canvas, shape=ROUND, width=4, status=STATUS_ON, 
relx=xpos, rely=ypos) ) 
Note also that we pass both the enclosing card_frame and the canvas to the construc- 
tor. This facilitates accessing the after method of the Widget base class to implement flashing. 


Finally, we populate the card rack. For the purpose of illustration, two of the FDDI cards 
have been replaced with Ethernet cards. Although this does not make much sense for this 
ATM switch, it demonstrates the ease with which the cards may be arranged. 
x = 0.0 
for i in range(12): 
if i in [0,2,2,3:4,5]: 
card =C6C110_FDDI (self.rack, slot=i) 
elif i in [6,7,8,9]: 
card =C6C110_ENET(self.rack, slot=i) 
else: 
card =C6C110_PSU(self.rack, slot=i) 
card.card_frame.place(x=x, y=0, anchor=NW) 
x = x + card.width 
Note that the actual card width is used to determine the placement of the next card, and 
not a calculated increment, as in the earlier example. 


Running EC6110.py displays the screen shown at the right of figure 9.9. The screen at 
the left of this figure illustrates the unpopulated rack. As in the earlier example, provision has 
been made to animate the components. Clicking anywhere on the enclosing chassis activates 
the animated display; this is not presented here and is left for you to try. 
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Figure 9.9 Cardrack implemented with GIF panels and overlaid components 
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— ——— 
Radio Shack oicivan Muctimeter 


Figure 9.10 
Digital multimeter 





The previous examples have illustrated the overall methods 
for developing GUI representation of panels and other 
devices. To further develop this theme we will look at a sim- 
ple but quite useful example. 

Many digital multimeters have serial interfaces which 
allow connection to a computer. I own a RadioShack 22- 
168A multimeter, which is shown in figure 9.10. The meter 
has 24 ranges that provide AC/DC voltage and current mea- 
surements, resistance, capacitance, frequency counting and 
other functions. The meter implements a simple serial proto- 
col which allows the currently-displayed value to be polled. 
Using a simple encoding scheme the current range selection 
can be deduced. 

Implementing a GUI to display the current state of the 
meter’s display is not particularly difficult. It is displaying the 
range that has been selected that introduces a challenge. One 
solution would be to display just the LCD panel at the top of 
the meter and then display the current range as text, either in 
the LCD or elsewhere. However this does not attempt to 
achieve photorealism and does not make for a particularly 
interesting example for you, the reader! 

The solution we are going to implement is to animate 
the selector knob on the meter so that it reflects the actual 
appearance of the meter to the user. This requires quite a lot 


of work, but, as you will see later, it results in an attractive GUI. 
These are the steps that we will go through to prepare a series of overlaid GIF images for 
the selector, as illustrated in figure 9.11: 


1 Obtain the base image with the selector at one position. 


n O oo FF W N 


Crop the selector as a rectangular selection. 

Retouch the image to remove the pixels surrounding the selector. 
Fill the background with a distinct color. 

Rotate the image 15 degrees. 

Crop the image to the same size as the original selection. 


Save the image as a transparent GIF image, using the colormap entry corresponding to 


the surroundings of the selector as the transparent color (the last image in the series, fig- 
ure 9.11(7), demonstrates the effect of displaying the overlaid image). 


You have probably judged me as criminally insane to propose generating 24 rotated GIF 


images simply to show an accurate view of the actual multimeter. Perhaps you are right, but 


please reserve your final judgement until after you have seen the finished result! 
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Figure 9.11 Steps to generate rotated selector images 





No As I began to develop this example, I encountered a problem with the serial 

communications to the multimeter. While investigating this problem I wanted 
to continue developing the GUI. I did this by building a simple test harness to simulate 
input from the device. I am going to present development of this example by showing the 
test version first and then adding serial communications later. This technique is valuable 
to get an application started, since it is possible to simulate input from devices even if 
they are not available for your use (or too expensive for your boss to sign a purchase req- 
uisition so that you can get your hands on one!). 





Here is the code to implement the test version of the multimeter. First, we begin with the 
data file, defining the meter’s ranges, control tables, labels, and other key data. 


Example_9 1_data.py 


# Tag Run RFlag Units Key 


PRIMARY_DATA = [ O 
('DI', 1, 'OL', ‘mv', 'di'), 
('DI', 0, '', 'mV', 'di'), 
('OH', 1, 'OL.', 'Ohm', 'oh2000'), 
('OH', 0, '4', ‘Ohm', 'oh2000'), 
(‘OH', 1, '.OL', 'KOhm', 'oh2ko'), O 
(‘OH', 0, '2', 'KOhm', 'oh2ko'), 
(‘OH', 1, 'O.L', 'KOhm', 'oh20ko'), 


('CA', O, '2', 'nF', ‘calo'), 
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(GAT Orita 'uF', ‘cahi') 

Cy wg Say 'mV', 'dc200mv'), 

(° DE", Op. 128 vane 'dce2v'), 

CDE 04 3" WAP 'dc20v'), 

UDE yve tA; yti 'dc200v'), 

(1DE bys 0p hy NT 'dc1000v'), 

('ac', 0, '4', Ms "ac200v'), 

(PRO 0,692", "He, 'frh'), 

GER QO) u2 ty 'KHz', Lirk yy 

(PR?) Oy 294 'MHz', 'frm'), 

(SHE ee es ay ‘hfe'), 

(COS 0 4 EG ‘logic'), 

CN Oe ets K 'cont')] © 
SECONDARY_DATA = { Sa 
# Key m u A m V k M O n u FEF M XK Hz AC Control, Label 
tart (0, 0, 0, O, O, O, O, O, 0, 0, O, 0, 0, 0, 0, 'diode', 'DIO'), 
'oh2000': (Or Orr Or 0r 0 BD) Oy, Uy 0, Dye Oy Be By Be By 20m SE 
'oh2ko': (03 03a 0r 0y (05. dy, 04. 14.05.0704. 0. 0} 05. OF A20 y e 
'oh20ko': £00 Oy D5 Oy Ol De Ope Dy Op 0% Oe: Oy Oy 10> O, 20ROnM A r 4 
'oh200ko': (OTO 04. 04. 05 Ty. OF. Ay, Oy Oy, 07 07. 04.505 07 Y200KOhm";. 4"); 
‘oh2mo': (0, 0, O, 0, O, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, '2MOhm', ''), 
'oh20mo': CO 1050); 0), 205, 0 -Tyy ey 6045 0.05..:0; 0° 0p. 0; "“20MOhm*;- *")-; 
VErhis (050%. 055.0), 20 0), Oi 00%, 20%. 0% OF. 0; 05. 1. 0, Ereg “FREO"):. 
Whi kat < (Or 0% 07 0%. 05. 0%. 0; 07, 05. 07. 0; 07,1, Ly, OF MEFeqt, FREQ"); 
Vrms (O5 2055 <0: 20.0 209-10), 205" Oi 209 10) 0%-< Lp 0, 103 Ered" 7- VERBOS); 
'hfe': (0r Or Or O0 OO 0 Oa T 0; 0}. 0; thet HEEN) 
‘logic': (0, 0, 0, 0, O, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 'logic', 'LOGI'), 
"cont': (0,0) 04 0,7 DO, Oy) Be Oy, 0, Dy By, Dy 04-0, Dy Seonts, Poy 
TESTDATA = ['DI OL mV', "DI OL mV', "DI OL mV', (4) 

TDL OL mV', 'DI OL mV', 'DI OL mV', 








'DI 0422 mV', 'DI 0022 mV', 'DI 0003 mV', 
'DI 0001 mV', 'DI 0004 mV', 'DI 0001 mvV', 
'DI 0001 mV', 'DI 0001 mV', 'DI 0892 mvV', 


"OH OL. Ohm', ‘OH OL. Ohm', ‘OH OL. Ohm', 
'OH OL. Ohm', 'OH OL. Ohm', 'OH 007.8 Ohm', 
‘OH 014.7 Ohm', 'OH 001.1 Ohm', 'OH 116.3 Ohm', 
‘OH 018.3 Ohm', 'OH 002.9 Ohm', 'OH 003.0 Ohm', 
"OH OL. Ohm', ‘OH -OL KOhm', 'OH -OL KOhm', 
'OH -OL KOhm', 'OH -OL KOhm', 'OH -0.010KOhm', 





‘OH 0O.085KOhm', 'OH 0.001KOhm', 'OH 0.001KOhm', 
‘OH 0.047KOhm', 'OH 0.410KOhm', 'OH 0.277KOhm', 
'CA 0.000 nF', 'CA 0.000 nF', 'CA 0.000 nF', 
"CA 0.000 nF', 'CA 0.000 nF', 'CA 0.000 uF', 
'CA 0.000 uF', 'CA 0.000 uF', 'CA 0.000 uF', 


'DC 034.1 mv', 'DC 025.6 mv', 'DC 063.5 mv', 
'DC 072.3 mv', 'DC 040.7 mv', 'DC 017.5 mv', 
'DC 005.2 mv', 'DC 0.005 v', 'DC 0.002 ee 
'DC 0.001 v', 'DC 0.001 v', 'DC 0.001 MOG. 
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'FR 0.000 KHz', 'FR 0.001 KHz', 'FR 0.001 KHz', 
'FR 0.002 KHz', 'FR 0.000 KHz', 'FR 0.001 KHz', 
'FR 0.001 KHz', 'FR 0.000 KHz', 'HF 0000 t 





'HF 0000 ', 'HF 0000 ', 'HF 0000 G 
'HF 0000 ', 'HF 0000 ', 'HF 0000 is 
'HF 0000 ', 'LO xrdy ', 'LO rdy ', 
'LO rdy ', 'LO xrdy ', 'LO rdy ', 
'LO rdy ', 'LO - rdy ry 





PANEL_LABELS = [ 








(225, 80, ‘Arial', 'M', 'mhz'), 
(240, 80, ‘Arial’, 'K', 'khz'), 
(255, 80, 'Arial', VEZ A CRZ D 
(225, 95, 'Arial', 'm', 'ma'), 
(240, 95, 'Symbol', 'm', 'ua'), 
(255, 95, 'Arial', 'A', TAP, 

(240, 110, 'Arial', 'm', ‘'mv'), 
(255, 110, 'Arial', VE Gg ON Ya 
( 
( 
( 
( 
( 
( 
( 





220, 125, ‘Arial’; IKs “kory, 
240, 125, 'Arial', 'M', ‘'mo'), 
255, 125, 'Symbol', 'W', 'o'), 
225, 40y- “Arial; at, RE), 
240, 140, 'Symbol', 'm', ‘uf'), 
255, 1405 “Arial'; “Fly “E"), 
50, 110, 'Arial', 'AC','ac')] 





Code comments 


@ The first list defines the ranges that the meter is capable of supporting, stored as tuples. The 
Tag determines the category of the reading: 
# Tag Run RFlag Units Key 
PRIMARY_DATA = [ 
(‘DI', 1, 'OL', ‘mvt,  ‘di'), 
('DI', 0, '', 'mV', 'di'), 
The Key is used to get the data that controls annunciators on the screen. 
@ The over limit indicator is encoded (by changing the decimal point) to indicate the range 
that is currently selected. 
('OH', 1, '.OL', 'KOhm', 'oh2ko'), 
('OH', 1, 'O.L', 'KOhm', 'oh20ko'), 





Most of the ranges have an over limit value. 


© The Key in PRIMARY_DATA is used to access a row in the SECONDARY_DATA dictionary which 
defines which of the annunciators are to be “turned on” on the display: 


# Key m u A m V k M O n u F M K Hz AC Control, Label 
cdit; (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 'diode', 'DIO'), 
"oh2000': (0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, '2000hm', ''), 


© TESTDATA captures data in the format defined by the serial protocol for the meter. This data 
was captured directly from the meter using a data capture program (which was also used to 
debug the problem mentioned above). 


å 





[TESTDATA = ['DI OL mV', 'DI OL mV', “DI OL mV', 
'DI OL mV', 'DI OL mV', 'DI OL mV', 
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'DI 0422 mV', 'DI 0022 mV', ‘DI 
'DI 0001 mV', 'DI 0004 mV', ‘DI 
'DI 0001 mv", ‘DI. 0001 mV', ‘DI 


0003 mV', 
0001 mV', 
0892 mV', 


The data is sent as a 14-character string. The first two characters (Tag) determine the 


category. The position of the decimal point, in conjunction with the units, determines the 


range. 


Here is the main code to support the application: 


Example_9_1.py 


from Common 
from Tkinter 


import * 
import * 


from Example_9_1_data import * 
import sys, time, string 


class MeterServer: 
def __init__(self): 
# Open up the serial port 


pass 


def poll(self): 
import random 
choice = random.choice(range(0, len(TESTDATA) -1) ) 
return TESTDATA[choice] 





class MultiMeter: 
def __init__(self, master): 


self. 
self. 
self. 


self. 
self. 
self. 


self. 
self. 


self. 
self. 
self. 


self. 
self. 
self. 
self. 
self. 
self. 


root = master 
root.title("Digital Multimeter") 
root.iconname ('22-168a') 


holdval = '0.0' 
curRange = None 
lineOpen = FALSE 


oe 


canvas = Canvas(self.root, width=300, height=694) 
canvas.pack(side="top", fil11=BOTH, expand='no') 


img = PhotoImage(file='images/multimeter.gif') 
canvas.create_image(0,0,anchor=NW, image=self.img) 


buildRule() 


root.update() 

root.after(5, self.buildSymbols) 
dataReady = FALSE 

root.after(5, self.buildScanner) 
multimeter = MeterServer () 
root.after(500, self.doPoll) 


def buildSymbols (self): 
for x, y, font, txt, tag in PANEL LABELS: 














self.canvas.create_text(x, y, text=txt, 
font=(font, 12), 
fill="gray75", 
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anchor = CENTER, 
tags=tag) 


def buildRule(self) : O 
self.canvas.create_line(75,150, 213,150, 
width=1, fill="#333377") 
self.Xincr = 140.0/40.0 
self.X = x = 75 
self.X1 = 213 
y= 150 
lbli = 0 


for i in range(40): 


lbl = v 
if i in [0,9,19,29,39]: 
hy - =6 
lbl = `lbli` 


lbli = 1lbli + 5 
elif- -i in [5,14,24,34]: 
h=4 
else: 
hus: 2 
self.canvas.create_line(x,y, x,y-h, 
width=1, £i11="#333377") 


af Diels 
self.canvas.create_text(x, y-5, text=lbl, 
font=("Arial", 6), 
£i11="#333377", 
anchor = S), 
x = x + self.Xincr 


def startAnimation(self 
self.animX = self.X 
self.action = TRUE 
self.root.after(30, self.animate) 








Code comments 


@ The test version of our code does not initialize the serial interface: 
def __init__(self): 
# Open up the serial port 
pass 
@ The poll method retrieves a random entry from the TESTDATA list, simulating a poll of the 
meter: 
def poll(self): 
import random 


choice = random.choice(range(0, len(TESTDATA) -1) ) 
return TESTDATA[choice] 





© This section of code illustrates how to arrange for an operation to occur as a background task. 
The methods buildSymbols and buildScanner are set up to run as callbacks after a few 
milliseconds. 
self.root.after(5, self.buildSymbols) 


AND NOW FOR A MORE COMPLETE EXAMPLE 225 











self.dataReady = FALSE 
self.root.after(5, self.buildScanner) 
self.multimeter = MeterServer () 
self.root.after(500, self.doPoll) 


buildScanner converts the GIF files to photo images and this is a time-consuming 
task. By moving the initialization to the background, we can display the base GUI immedi- 
ately (although the user has to wait for all of the images to load before proceeding). 


Q buildrule constructs tickmarks used by the multimeter to indicate the currently measured 
value relative to full-scale deflection of the selected range and to animate a graphic when the 
value is over range. 


Example_9_1.py (continued) 


def animate(self): O 
if self.action: 
self.canvas.create_line(self.animXx,155, self.animx, 167, 
width=2, fill="#333377", 
tags='anim') 
self.animX = self.animX + self.Xincr 
if self.animX > self.X1: 
self.animX= self.X 
self.canvas.delete('anim') 
self.root.after (30, self.animate) 
else: 
self.canvas.delete('anim') 


def stopAnimation (self): 
self.action = FALSE 


def buildScanner (self): 
self.primary_lookup = {} 
for key, hasr, rfmt, un, sec in PRIMARY_DATA: 
if not self.primary_lookup.has_key (key): 
self.primary_lookup[key] = [] 
self.primary_lookup[key] .append( (hasr, rfmt, un, sec)) 


keys = SECONDARY_DATA.keys () 
for key in keys: 
img = SECONDARY_DATA [key] [-2] 
try: 
if getattr(self, ‘i%s' % key): 
pass # Already done... 
except: 
setattr(self, ‘i%s’ % key, 
PhotoImage (file="images/%s.gif" % img) ) 
self.dataReady = TRUE 


def doPoll(self): 
if self.dataReady: 
result = self.multimeter.poll() 
if result: 
self.updateDisplay (result) 
self.root.after(1000, self.doPoll) 


def getRange(self, tag, val, units): QO 
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matchlist = self.primary_lookup[tag] 
if not matchlist: return None 
gotIndex = None 
gotOpenLine = FALS 
for hasr, rfmt, un, sec in matchlist: 
if hasr and (string.find(val, 'L') >= 0): 
if rfmt == string.strip(val): 
gotIndex = sec 
gotOpenLine = TRUE 





Gl 


else: 
decimal = string.find(val, '.') 
if decimal > 0: 
if rfmt == ‘decimal’: 
gotIndex = sec 
else: 
if not rfmt: # No decimals 
gotIndex = sec 
if gotIndex: 


if not string.strip(units) == string.strip(un): 


gotIndex = None 
if gotIndex: 
break 
return (gotIndex, gotOpenLine) 


def updateDisplay(self, result): 
self.canvas.delete('display') 
tag = result[:2] 
val = result[3:9] 
units = result [9:13] 
# display the hold value 
redraw = FALSE 
try: 
hold = string.atof(self.holdVal) 
nval = string.atof (val) 
if hold <= 0.0: 
if nval < 0.0: 
if nval < hold: 
self.holdval = val 
redraw = TRUE 
else: 
hold = 0.0 
if hold >= 0.0 and not redraw: oO 
if nval >= 0.0: 
if nval > hold: 
self.holdval = val 
redraw = TRUE 
else: 
self.holdval = '0.0' 
redraw = TRUE 
except ValueError: 
self.holdVal = '0.0' 
redraw = TRU. 








GI 


if redraw: 
self.canvas.delete('holdval') 


AND NOW FOR A MORE COMPLETE EXAMPLE 


227 











self.canvas.create_text (263, 67, text=self.holdVval, 
font=("Digiface", 16), 
£i11="#333377", 
anchor = E, 
tags="holdval") 


range, openline = self.getRange(tag, val, units) 
if range: # Change the control to reflect the range 
if not self.curRange == range: 
self.curRange = range 
self.canvas.delete('control') 
self.canvas.create_image(146, 441,anchor=CENTER, 
image=getattr(self, ‘its’ % range). 
tags="control") 
self.holdval = '0.0' # reset 
if openline: 
self.startAnimation() 
else: 
self.stopAnimation() 














# Now we will update the units symbols on the display 
ma,ua,a,mv,v,ko,mo,o,nf,uf,f,mhz,khz,hz,ac, ctrl, lbl = \ 
SECONDARY_DATA [range] 


for tag in ['ma','ua','a','mv','v','ko','mo','o', 
int “ai; bE; tiie; RAs) he ‘ee’ Ts 
self.canvas.itemconfig(tag, 
fill=['gray75','#333377'] [eval (tag) ]) 
# Update the label field if there is one 
self.canvas.delete('label') 
if Tol 
self.canvas.create_text(55, 150, text=l1bl, 
font=("Arial", 12), 
Fill="#333377", 
anchor = CENTER, 
tags="label") 











# Finally, display the value 
self.canvas.create_text(214, 100, text=val, 
font=("Digiface", 48), 
Fi LIa"#S 33377", 
anchor = E, 
tags="display") 


if _ name == '_main_': 
root = Tk() 
multimeter = MultiMeter (root) 
multimeter.root.mainloop () 





Code comments (continued) 


© The animate method displays a rapidly increasing row of vertical bars which reset when they 
reach the right-hand side of the display. 


@ buildscanner builds a dictionary from PRIMARY_DATA to provide the primary lookup for 
the messages received from the meter. The GIF images are also loaded as Photolmages. 
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getRange parses the message received from the meter to determine the range and value to be 


displayed. 


© The meter holds the highest (or lowest) value measured. This code displays this data. The 
code is longer than we might expect because we have to be able to detect the most positive or 
the most negative value. 


© In this section of code, we change the overlaid selector knob position if the range has changed. 
Note that the previous image, tagged as control, is deleted first. 


@ Finally, we update the annunciators according to the currently selected range. To simplify 
this, we fill the text stroke with either a very light or dark gray. 


If we run Example_9_1.py we will observe the display 
shown in figure 9.12. As each value is displayed, the range 
selector is animated to indicate the range for the value. An 
example of the display is shown in figure 9.13. 

To complete the example, we simply need to add asynchro- 
nous support to connect the multimeter. This makes use of a 
Python extension module, siomodule, which is readily available 
from the Python language site (http://www.python.org), with 
one small change to support an idiosyncrasy of the meter’s hand- 
shake protocol, but more about that in a moment. Extension 
modules are covered in detail in a later section, “Putting it all 
together...” on page 311. This module makes use of a commer- 
cial dll, which has been made available for general use (see “Sio- 
module” on page 625 for details). The necessary code changes 
are in Example_9_2.py: 





Figure 9.12 Simulating Figure 9.13 Range selector animation 
measurements 


Example_9 2.py 


from crilib import * Load serial 
import sys, regex, serial, time, string, os 


IGNORE = '\n\r' 


class RS232(serial.Port) : o Init UART 





def _ init_ (self): 
serial.Port.__init_ (self) 
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def open(self, cfg): 
self.debug = cfg['debug' ] 
self._trace('RS232.open') 





cfg['cmdsEchoed'] = FALSE Setup params 
cfg['cmdTerm' ] = er 

cfg['rspTerm' ] So re 

cfg['rspType'] = serial .RSP_TERMINATED 











serial.Port.open(self, cfg) 


class MeterServer: 
def _ init_ (self): 
# Open up the serial port 


try: 
d = serial.PortDict() Connection 
a['port'] = serial.COM1 
d['baud'] = serial.Baud1200 
d['parity'] = serial.NoParity 
d['dataBits'] = serial.WordLength7 
d['stopBits'] = serial.TwoStopBits 
d['timeoutMs'] = 1500 O 
d['rspTerm'] = IGNORE 
d['rtsSignal'] = 'C' (6) 
da['debug' ] = FALSE 
self.fd = RS232() 
self.fd.open(d) 

except: 
print 'Cannot open serial port (COM1)' 
sys.exit() 


def poll(self): 


try: 
line = self.fd.write('D\r') 
# OK, read the serial line (wait maximum of 1500 mSec) 
inl = self.fd.readTerminated() 
return inl 
except: 


return 'XX Off ' O 





Code comments 


@ The serial module wraps the sio module, which is a dll. 
from crilib import * 
import sys, serial, time, string, os 


crilib contains simple constants. 


© This time we have to initialize the UART (Universal Asynchronous Receiver Transmitter): 
def __init__(self): 
serial.Port.__ init__(self) 
© The terminators for the serial protocol are defined. Although we are not turning debug on for 
this example, the necessary initializers are given to help you reuse the code. 


© The communication parameters for the UART are set. 


serial.cCoM1 
serial.Baud1200 


d['port'] 
d['baud'] 


Il 
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da['parity'] = serial.NoParity 
da['dataBits'] = serial.WordLength7 
da['stopBits'] = serial.TwoStopBits 
Note the somewhat unusual format and slow communication speed. However, the 
meter is a quite simple device, and not very expensive, so we can make an exception here. 


@ The read is blocking, which is unusual for a GUI. Since there are no user controls on the dis- 
play, we do not need to worry about exposing the event loop. So, if the meter failed to 
respond to a request for data, we might lock up for a a second or so. 


@ This is where the meter’s unusual handshaking protocol is handled. This is the reason I con- 
structed the test version of the code, because I could not get the device to respond to the poll 
request initially. I had to use a software datascope to monitor the control lines on the serial 
interface to determine what the device needed to communicate. Unusually, it required 
Request-To-Send (RTS) to go low before it would send anything. The serial module, as 
obtained from the Python FTP site, has RTS strapped high. A simple change fixes this prob- 
lem. Here we force RTS low. 

da['rtsSignal'] = 'C' 

@ The meter has to be polled to get the current value measured. 

line = self.fd.write('D\r') 

© If the poll times out, we assume that the multimeter is switched off and we fabricate a message 
to show an appropriate value on the display. 

return 'XX Off 


The minimal changes to serial.py are shown here: 


serial.py (changes only) 


def __init__(self): 
self._dict = {} 


self._dict['rspType'] = RSP_BEST_EFFORT 
self._dict['rspFixedLen'] = 0 
self. dict['rtsSignal'] = 'S' 
self. dict['dtrSignal'] = 'S' 


def __setitem__(self, key, value): 





elif key == 'debug' or key == 'cmdsEchoed': 
if type(value) != IntType: 
raise AttributeError, 'must be a boolean value' 
elif key == 'rtsSignal': 


if not value[:1] in 'CS': 
raise AttributeError, 'Illegal rtsSignal value' 
elif key == 'dtrSignal': 
if not value[:1] in 'CS': 
raise AttributeError, 'Illegal dtrSignal value' 





self._dict[key] = value 


def open(self, cfg): 
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self._chkSioExec(SioRxClear, (port,) ) 

self. chkSioExec(SioDTR, (port, cfg['dtrSignal'][:1])) 
self. chkSioExec(SioRTS, (port, cfg['rtsSignal'][:1])) 
self._chkSioExec(SioFlow, (port, 'N')) 


Running Example_9_2.py displays the multimeter. Since there are no changes to the dis- 
play methods, the display is indistinguishable from the one shown in figure 9.12, so it will not 
be shown here. 


Virtual machines using POV-Ray 


Of course, some applications may not have a physical device; for these cases, it is possible to 
create ray-traced images (using Persistence of Vision POV-Ray, or other rendering systems, 
for example) to create virtual machines. 

Figure 9.14 shows an example of a ray-traced GUI which has been used in a commercial 
application. This employs the same overlay technique used to develop the front panel shown 
in figure 9.9, except that the image was completely fabricated. The application that this GUI 
supported was intended to be used by airline pilots, and so the display is constructed to be sim- 
ilar to some of the radio stacks encountered in aircraft. The GUI has a strong three-dimen- 
sional content, with shadows and highlights. All of this is computer generated by POV-Ray. 
The text, LEDs and navigable buttons are overlaid Tkinter widgets. The important feature to 
note is that the application has nothing to do with radio stacks; it is really a database access 
application. This is an application with punch! 
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Figure 9.14 Ray-traced user interface 
Photo courtesy INVOTEC, Inc. 


CHAPTER 9 PANELS AND MACHINES 











9.6.1 





And now for something completely different... 
#10 The Example 


I’m sorry! I had to use that title. The last example is going to illustrate just how unusual a user 
interface can become. Readers who are familiar with popular computer games such as Myst 
and Riven will share with me their love of ray-traced user interfaces. This is a simplistic ver- 
sion of such an interface. I’m not going to detail the development of ray-traced images, as 
many texts cover the subject. Let’s start with the basic image shown in figure 9.15. 


Figure 9.15 Base scene 
generated with POV-Ray 


The figure looks best in color, so you may want to obtain the image online. Since you 
may wish to solve the simple puzzle presented by this example, I will present only a fragment 
of the code for the application. We are using the overlay techniques presented in this chapter 
to bind functionality to the two “buttons” in the display. This requires special handling, since 
the two “buttons” need to take focus, show a highlight when they have focus, and receive but- 
ton-down events. The following code excerpt manages these buttons. 


Example_9 3.py 


class Machine: 
def __init__(self, master): 
self.root = master 


self.bl = self.canvas.create_oval (216,285, 270,340, fill="", 
outline='#226644', width=3, tags='b_1') 

self.canvas.tag_bind(self.b1, "<Any-Enter>", self.mouseEnter) 

self.canvas.tag_bind(self.b1l, "<Any-Leave>", self.mouseLeave) 


self.b2 = self.canvas.create_oval (216,355, 270,410, fill="", 
outline='#772244', width=3, tags='b_2') 
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self.canvas.tag_bind(self.b2, "<Any-Enter>", self.mouseEnter) 
self.canvas.tag_bind(self.b2, "<Any-Leave>", self.mouseLeave) 





Widget .bind(self.canvas, "<1>", self.mouseDown) 


self.buttonAction = {'b_1': self.bl_action, 
'b_2': self.b2_action} 


def mouseDown(self, event): 
# See if we're on a button. If we are, it 
# gets tagged as CURRENT for by Tk. 
if event.widget.find_withtag (CURRENT) : 
tags = self.canvas.gettags('current') 
if '_' in tags[0]: 
self.buttonAction[tags[0]] () 








def mouseEnter(self, event): 
# The CURRENT tag is applied to 
# The object the cursor is over. 
tags = self.canvas.gettags('current') 
usetag= tags[0] 
self.lastcolor = self.canvas.itemcget(usetag, 'outline') 
self.canvas.itemconfig(usetag, outline=Color.HIGHLIGHT) 
self.canvas.itemconfig(usetag, fill=self.lastcolor) 


def mouseLeave(self, event): 
tags = self.canvas.gettags('current') 
usetag= tags[0] 
self.canvas.itemconfig(usetag, outline=self.lastcolor) 
self.canvas.itemconfig(usetag, fill="") 


def bl_action(self): 
if self.inSet: 
value = eval(self.digits[self.curDigit] ) 
value = value + 1 
exec('%$s = value' % self.digits[self.curDigit] ) 
self .makeTime() 
self.displaySet () 


def b2_action(self): 
if not self.inSet: 
self.inSet = TRUE 
self.displaySet () 
self.root.after(1000, self.displayTime) 
else: 
self.curDigit = self.curDigit + 1 
if self.curDigit > 3: 
self.inSet = FALSE 
self.canvas.delete('settag') 
self .mouseLeave (None) eo 
self .doCountdown () 








Code comments 


@ We create two circles surrounding the spheres on the display, colored to match the existing 


display. Note that the circle has no fill color, and is thus transparent. 
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self.bl = self.canvas.create_oval (216,285, 270,340, fill="", 
outline='#226644', width=3, tags='b_1') 
© The transparent fill on the circle has a side effect: a transparent object does not receive button 
events, so we bind enter and leave events to the line drawn for the circle. 
self.canvas.tag_bind(self.b2, "<Any-Enter>", self.mouseEnter) 
self.canvas.tag_bind(self.b2, "<Any-Leave>", self.mouseLeave) 
Widget.bind(self.canvas, "<1>", self.mouseDown) 
We also bind left-mouse-button to the whole canvas. Note that we use the bind method 
of the mixin Widget to bind the event. 


©  self.buttonAction is a very simple dispatcher: 
self.buttonAction = {'b_1': self.bl_action, 
"b_2': self.b2_action} 
© mouseDown dispatches to the appropriate function using the tag of the canvas item receiving 
the event: 


def mouseDown(self, event): 
if event.widget.find_withtag (CURRENT) : 
tags = self.canvas.gettags('current') 
if '_' in tags[0]: 
self.buttonAction[tags[0]] () 


@ mousernter fills the circle with a color so that it can receive button events: 





def mouseEnter(self, event): 
tags = self.canvas.gettags('current') 
usetag= tags[0] 
self.lastcolor = self.canvas.itemcget(usetag, 'outline') 
self.canvas.itemconfig(usetag, outline=Color.HIGHLIGHT) 
self.canvas.itemconfig(usetag, fill=self.lastcolor) 


@ mouseLeave removes the fill as the cursor leaves the button: 


def mouseLeave(self, event): 
tags = self.canvas.gettags('current') 
usetag= tags[0] 
self.canvas.itemconfig(usetag, outline=self.lastcolor) 
self.canvas.itemconfig(usetag, fill="") 
@ Finally, when certain conditions have been met, we call mouseLeave directly to remove the 
highlight, even if the cursor is over the canvas item: 


self.canvas.delete('settag') 
self .mouseLeave (None) 


If you run Example_9_3.py and work out the sequence, you should see a display similar 
to the one shown in figure 9.16. 
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Figure 9.16 Running 
the puzzle 
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The material in this chapter may seem to be very inappropriate for uses other than mechanical 
devices. Yet there is no reason that information about a system which has no real “front 
panel” cannot be given an abstract interface. If combinations of the techniques presented in 
this chapter are used, quite complex devices can be displayed to present status indicators and 
input devices for users. I hope that you have fun with these examples—there is something very 
satisfying about generating representations of devices. 
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and rubber lines 


10.1 Drawing onacanvas 238 10.5 Stretching canvas objects 258 

10.2 A more complete drawing 10.6 Some finishing touches 262 
program 244 10.7 Speed drawing 271 

10.3 Scrolled canvases 251 10.8 Summary 275 


10.4 Ruler-class tools 254 


Despite the title, this chapter covers some of the techniques used to build drawing tools and 
interfaces which allow the user to create and move objects around in a GUI. The chapter is 
not meant to be a complete guide to developing a new “paint” tool, but I will provide you 
with some useful templates for drawing objects on a canvas, using rubber lines and rearrang- 
ing objects on a canvas. You have already seen the effect of drawing items on a canvas in ear- 
lier chapters—this chapter reveals a little more detail on how to create and maintain drawn 
objects. 

Some of the examples are Tkinter adaptations of Tk demonstration programs; they may 
be used as an additional guide to converting Tcl/Tk scripts to Tkinter. I have avoided the 
temptation to completely rework the code, since a side-by-side comparison would reveal how 


well Tkinter supports Tk. 
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10.1 


Drawing on a canvas 


We have already encountered several examples of objects drawn on canvases. However, these 
objects were drawn to represent physical objects on front panels and to create images pro- 
grammatically. Now we need to allow the user to create drawn objects on the canvas. 

Almost all drawing operations define a bounding box which encloses the object. The 
bounding box is expressed as a pair of x/y coordinates at the top-left and bottom-right corners. 
Lines are special cases; they have a start and end coordinate which does not have to corre- 
spond to the coordinates of its bounding box. The bounding box for a line will always be the 
top-left and bottom-right coordinates. It is important to note that Tk does not guarantee that 
the bounding box exactly bounds the object, so some allowances may have to be made in critical 
code. This is illustrated in figure 10.1. 


x1,y1 x1) 








L 4 Ss 2 
x2,Y2 x2,y2 start x2,y2 


Figure 10.1 Bounding boxes for rectangles, ovals, and lines 


Curved lines (not arcs) are defined as a series of straight lines, each with its own bounding 
box. Although we will see the application of these object types in some of the examples, they 
really require special consideration. 

Let’s start with a very simple drawing program, inspired by one of the examples in Dou- 
glas A. Young’s The X Window System: Programming and Applications with Xt. This example 
allows the user to draw lines, rectangles and ovals on a canvas and then select each of these 
objects. The original example was written in C using X Window, so I have obviously Tkin- 
terized it. It does not allow editing of the resulting drawn objects, so it is somewhat akin to 
drawing on soft paper with a very hard pencil! 
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from Tkinter import * 
import Pmw, AppShell, math 


class Draw(AppShell.AppShell) : 
usecommandarea = 1 


appname = 'Drawing Program - Version 1' 
frameWidth = 800 
frameHeight = 600 


def createButtons (self): 
self.buttonAdd('Close', helpMessage='Close Screen', 
statusMessage='Exit', command=self.close) 
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Figure 10.2 A very simple drawing program 


def createBase(self): 


self.width = self.root.winfo_width()-10 

self.height = self.root.winfo_height()-95 

self.command= self.createcomponent('command', (), None, 
Frame, (self.interior(),), width=self.width*0.25, 


height=self.height, background="gray90") 
self.command.pack(side=LEFT, expand=YES, fill=BOTH) 


self.canvas = self.createcomponent('canvas', (), None, 
Canvas, (self.interior(),), width=self.width*0.73, 
height=self.height, background="white") 

self.canvas.pack(side=LEFT, expand=YES, fi11=BOTH) 


Widget.bind(self.canvas, "<Button-1>", self.mouseDown) 


Widget.bind(self.canvas, "<Buttonl-Motion>", self.mouseMotion) 
Widget.bind(self.canvas, "<Buttonl-ButtonRelease>", self.mouseUp) 


self.radio = Pmw.RadioSelect(self.command, labelpos = None, 


buttontype = 'radiobutton', orient = VERTICAL, 
command = self.selectFunc, hull_borderwidth = 2, 
hull_relief = RIDGE, ) 

self.radio.pack(side = TOP, expand = 1) 


self.func = {} 

for text, func in (('Select', None), 
('Rectangle', self.drawRect), 
('Oval', self.drawOval), 
('Line', self.drawLine) ): 
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self.radio.add(text) 
self.func[text] = func 
self.radio.invoke('Rectangle') 


def selectFunc(self, tag): 
self.currentFunc = self.func[tag] 


def mouseDown(self, event): 

self.currentObject = None 

self.lastx = self.startx = self.canvas.canvasx(event.x) 

self.lasty = self.starty = self.canvas.canvasy(event.y) 

if not self.currentFunc: 
self.selObj = self.canvas.find_closest (self.startx, 

self.starty) [0] 

self.canvas.itemconfig(self.selObj, width=2) 
self.canvas.lift(self.selObj) 


def mouseMotion(self, event): 
self.lastx = self.canvas.canvasx(event.x) 
self.lasty = self.canvas.canvasy(event.y) 
if self.currentFunc: 
self.canvas.delete(self.currentObject) 
self.currentFunc(self.startx, self.starty, 
self.lastx, self.lasty, 
self.foreground, self .background) 


def mouseUp(self, event): 
self.lastx = self.canvas.canvasx(event.x) 
self.lasty = self.canvas.canvasy(event.y) 
self.canvas.delete(self.currentObject) 
self.currentObject = None 
if self.currentFunc: 
self.currentFunc(self.startx, self.starty, 
self.lastx, self.lasty, 
self.foreground, self.background) 
else: 
if self.selObj: 
self.canvas.itemconfig(self.selObj, width=1) 


def drawLine(self, x, y, x2, y2, fg, bg): 
self.currentObject = self.canvas.create_line(x,y,x2,y2, 
fill=fg) 


def drawRect (self, x, y, x2, y2, fg, bg): 
self.currentObject = self.canvas.create_rectangle(x, y, 
x2, y2, outline=fg, fill=bg) 


def drawOval(self, x, y, x2, y2, fg, bg): 
self.currentObject = self.canvas.create_oval(x, y, x2, y2, 
outline=fg, fill=bg) 


def initData(self): 





self.currentFunc = None 
self.currentObject = None 
self.selObj = None 
self.foreground = 'black' 
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self .background = 'white' 


def close(self): 
self.quit() 


def createInterface(self): 
AppShell.AppShell.createInterface (self) 
self.createButtons () 
self.initData() 
self.createBase() 


if _name__ == '_main_': 
draw = Draw() 
draw.run() 





Code comments 


@ This example is completely pointer-driven so it relies on binding functionality to mouse 
events. We bind click, movement and release to appropriate member functions. 
Widget .bind(self.canvas, "<Button-1>", self.mouseDown) 
Widget .bind(self.canvas, "<Buttonl-Motion>", self.mouseMotion) 
Widget .bind(self.canvas, "<Buttonl-ButtonRelease>", self.mouseUp) 
@ This simple example supports three basic shapes. We build pmw.RadioSelect buttons to link 
each of the shapes with an appropriate drawing function. Additionally, we define a selection 
option which allows us to click on the canvas without drawing. 


© The mouseDown method deselects any currently selected object. The event returns x- and y- 
coordinates for the mouse-click as screen coordinates. The canvasx and canvasy methods 
of the Canvas widget convert these screen coordinates into coordinates relative to the canvas. 


def mouseDown(self, event): 
self.currentObject = None 
self.lastx = self.startx = self.canvas.canvasx(event.x) 
self.lasty = self.starty = self.canvas.canvasy(event.y) 
Converting the x- and y-coordinates to canvas coordinates is a step that is often forgot- 
ten when first coding canvas-based applications. Figure 10.3 illustrates what this means. 


screen x = 400 screen x = 700 
canvas x = 325 canvas x = 325 


screen y= 300 + | 600 
canvas y= 250 


screen y= 510 


= 250 
Enea Figure 10.3 Relationship 


< y between screen and canvas 
coordinates 


800 
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When the user clicks on the canvas, the click effectively goes through to the desktop and these 
coordinates are returned in the event. Converting to canvas coordinates returns the coordi- 
nates relative to the canvas origin, regardless of where the canvas is on the screen. 


If no drawing function is selected, we are in select mode, and we search to locate the nearest 
object on the canvas and select it. This method of selection may not be appropriate for all 
drawing applications, since the method will always find an object, no matter where the canvas 
is clicked. This can lead to some confusing behavior in certain complex diagrams, so the selec- 
tion model might require direct clicking on an object to select it. 
if not self.currentFunc: 
self.selObj = self.canvas.find_closest(self.startx, 
self.starty) ) 
self.canvas.itemconfig(self.selObj, width=2) 
self.canvas.1lift(self.selObj) 
Having selected the object, we thicken its outline and raise (lift) it to the top of the 
drawing stack, as shown in figure 10.4. 


Drawing Program - Version 2 
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As the mouse is moved (with the button down), we receive a stream of motion events. Each of 
these represents a change in the bounding box for the object. Having converted the x- and y- 
coordinates to canvas points, we delete the existing canvas object and redraw it using the 
current function and the new bounding box. 


self.canvas.delete(self.currentObject) 

self.currentFunc(self.startx, self.starty, 
self.lastx, self.lasty, 
self.foreground, self.background) 


The drawing methods are quite simple; they're just creating canvas primitives within the 
bounding box. 


def drawLine (self, x, y, x2, y2, fg, bg): 
self.currentObject = self.canvas.create_line(x,y,x2,y2, 
fill=fg) 
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10.1.1 Moving canvas objects 


The selection of objects in the first example simply raises them in the display stack. If you 
were to raise a large object above smaller objects you could quite possibly prevent access to 
those objects. Clearly, we need to provide a more useful means of manipulating the drawn 
objects. Typically, draw tools move objects in response to a mouse drag. Adding this to the 
example is very easy. Here are the modifications which have been applied to draw. py: 


Drawing Program - Version 2 


Figure 10.5 Moving objects 
on a canvas 





draw2.py 


def mouseMotion(self, event): 
cx = self.canvas.canvasx(event.x) -0 
cy = self.canvas.canvasy(event.y) 
if self.currentFunc: 
self.lastx = cx 
self.lasty = cy © 
self.canvas.delete(self.currentObject) 
self.currentFunc(self.startx, self.starty, 
self.lastx, self.lasty, 
self.foreground, self.background) 


else: 
if self.selObj: 
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cy-self.lasty) 
self.lastx 
self.lasty 


cx 
cy 


self.canvas.move(self.selObj, cx-self.lastx, o 





Code comments 


We need to store the x- and y-coordinates in intermediate variables, since we need to deter- 
mine how far the mouse moved since the last time we updated the screen. 


If we are drawing the object, we use the x- and y-coordinates as the second coordinate of the 
bounding box. 


If we are moving the object, we calculate the difference between the current location and the 
last bounding box location. 


A more complete drawing program 


The examples so far demonstrate basic drawing methods, but a realistic drawing program 


must supply many more facilities. Let’s take a look at some of the features that we are adding 
in this example before studying the code: 


Drawing Program - Version 3 
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1 A Toolbar to give access to a number of specific drawing tools and options: 


e Drawing tools for freehand curves, smoothed curves, straight (rubber) lines, open 
and filled rectangles, and open and filled ovals. 

e Provision to set the color of the line or outline of a drawn object. 

e Provision to set the width of the line or outline of a drawn object. 

e Provision to set the fill color of an object. 

e A limited number of stipple masks (to allow variable transparency). 


2 Holding down the SHIFT key draws rectangles and ovals as squares and circles respectively. 


3 An option to generate a PostScript file rendering the current content of the canvas. 
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4 A refresh option to repaint the screen. 


5 Balloon help (provided through AppShell, which was introduced on page 155). 


Here is the source to support the functionality: 


draw3.py 


from Tkinter import * 
import Pmw, AppShell, math, time, string 


class ToolBarButton (Label): 
def __init__(self, top, parent, tag=None, image=None, 


command=None 


statushelp='', balloonhelp='', height=21, width=21, 
pady=0, 


bd=1, activebackground='lightgrey', padx=0, 
state='normal', bg='grey'): 


Label. init__(self, parent, height=height, width=width, 


relief='flat', bd=bd, bg=bg) 
self.bg = bg 
self.activebackground = activebackground 
if image != None: 
if string.split(image, '.')[1] == 'bmp': 


self.Icon = BitmapImage(file='icons/%s' 


else: 
self.Icon = PhotoImage(file='icons/$%s' 
else: 


% 


% 


self.Icon = PhotoImage(file='icons/blank.gif') 


self.config(image=self.Icon) 


self.tag = tag 
self.icommand = command 





self.command = self.activate 
self.bind("<Enter>", self.buttonEnter) 
self .bind("<Leave>", self .buttonLeave) 
self.bind("<ButtonPress-1>", self .buttonDown) 
self .bind("<ButtonRelease-1>", self.buttonUp) 

( 


self.pack 


H- 


f balloonhelp or statushelp: 


self.state = state 


def activate (self): 
self.icommand(self.tag) 





def buttonEnter(self, event): 
if self.state != 'disabled': 
self.config(relief='raised', bg=self.bg) 


def buttonLeave(self, event): 
if self.state != 'disabled': 
self.config(relief='flat', bg=self.bg) 





def buttonDown(self, event): 
if self.state != 'disabled': 


image) 


image) 


side='left', anchor=NW, padx=padx, pady=pady) 


top.balloon().bind(self, balloonhelp, statushelp) 


self.config(relief='sunken', bg=self.activebackground) 
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def buttonUp(self, event): 
if self.state != 'disabled': 
if self.command != None: 
self .command() 
time.sleep(0.05) 
self.config(relief='flat', bg=self.bg) 


class Draw(AppShell.AppShell1) : 
usecommandarea = 1 


appname = 'Drawing Program - Version 3' 
frameWidth = 840 
frameHeight = 600 


def createButtons (self): 

self.buttonAdd('Postscript', 
helpMessage='Save current drawing (as PostScript)', 
statusMessage='Save drawing as PostScript file', 
command=self.ipostscript) 

self .buttonAdd('Refresh', helpMessage='Refresh drawing', 
statusMessage='Redraw the screen', command=self.redraw) 

self.buttonAdd('Close', helpMessage='Close Screen', 
statusMessage='Exit', command=self.close) 


def createBase(self): 
self.toolbar = self.createcomponent('toolbar', (), None, 
Frame, (self.interior(),), background="gray90") 
self.toolbar.pack (£i11=X) 


self.canvas = self.createcomponent('canvas', (), None, 
Canvas, (self.interior(),), background="white") 
self.canvas.pack(side=LEFT, expand=YES, f£1i11=BOTH) 





Widget .bind(self.canvas, "<Button-1>", self.mouseDown) 

Widget .bind(self.canvas, "<Buttonl-Motion>", self.mouseMotion) 
Widget .bind(self.canvas, "<Buttonl-ButtonRelease>", self.mouseUp) 
self.root.bind("<KeyPress>", self.setRegular) 
self.root.bind("<KeyRelease>", self.setRegular) 


def setRegular(self, event): 
if event.type == '2' and event.keys == 'Shift_L': 
self.regular = TRUE 
else: 
self.regular = FALSE 


def createTools (self): 
self.func = {} 
ToolBarButton(self, self.toolbar, 'sep', ‘'sep.gif', 
width=10, state='disabled') 
for key, func, balloon in [ 


('pointer', None, 'Edit drawing'), 
('draw', self.drawFree, "Draw freehand' ) 
('smooth', self.drawSmooth, ‘Smooth freehand'), 
('line', self.drawLine, "Rubber line') 
('rect', self.drawRect, ‘Unfilled rectangle') 
(Crecen self.drawFilledRect, 'Filled rectangle'), 
('oval', self.drawOval, ‘Unfilled oval'), 
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('foval', self.drawFilledOval, 'Filled oval')]: 

ToolBarButton(self, self.toolbar, key, '%s.gif' % key, 
command=self.selectFunc, balloonhelp=balloon, 
statushelp=balloon) 

self.func[key] = func 


def createLineWidths(self): 


ToolBarButton(self, self.toolbar, 'sep', 'sep.gif', width=10, 
state='disabled') 
for width in ['1', '3', '5']: o 


ToolBarButton(self, self.toolbar, width, 'tline%s.gif' % \ 
width, command=self.selectWidth, 
balloonhelp='%s pixel linewidth' % width, 
statushelp='%s pixel linewidth' % width) 


def createLineColors(self): 
def createFillColors(self): 
def createPatterns (self): 


# --- Code Removed --~----------- 9-5-5555 5 5 nn nnn nnn nnn nnn nnn nnn nnn nnn-- 








Code comments 


@ The ToolBarButton class implements a simple iconic button. A bitmap or Photolmage may 


be used for the icon. 


@ We establish bindings for the Label widget, since we have to create our own button-press 
animation when the user clicks on the button or places the cursor over the button. 


© Forcing rectangles to be squares and ovals to be circles is achieved by binding a <Keypress> 


event to the root window. When we receive the callback, we have to check that the SHIFT key 


is pressed and set a flag accordingly. 


self.root.bind("<KeyPress>", self.setRegular) 
self.root.bind("<KeyRelease>", self.setRegular) 

def setRegular(self, event): 
if event.type == '2' and event.keys == 'Shift_Left’: 


self.regular = TRUE 





© We create a dispatch table for the various drawn object types, with a display name, function, 
and Balloon help text. 


@ The method to create each group of toolbar buttoons is essentially the same, so some of the 


code has been removed for brevity. 


draw3.py (continued) 


def selectFunc(self, tag): 
self.curFunc = self.func[tag] 
if self.curFunc: 
self.canvas.config(cursor='crosshair' ) 
else: 
self.canvas.config(cursor='arrow' ) 


def selectWidth(self, tag): 
def selectBackground(self, tag): 
def selectForeground(self, tag): 
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def selectPattern(self, tag): 
Fec Code Removed tetetete nnaan 


def mouseDown (self, event): 
self.curObject = None 
self.canvas.dtag('drawing' ) 
self.lineData = [] 
self.lastx = self.startx = self.canvas.canvasx(event.x) 
self.lasty = self.starty = self.canvas.canvasy(event.y) 
if not self.curFunc: 
self.selObj = self.canvas.find_closest(self.startx, 
self.starty) [0] 
self.savedWidth = string.atoi(self.canvas.itemcget( \ 
self.selObj, 'width')) 
self.canvas.itemconfig(self.selObj, 
width=self.savedWidth + 2) 
self.canvas.lift(self.selObj) 


def mouseMotion(self, event): 
curx = self.canvas.canvasx(event.x) 
cury = self.canvas.canvasy(event.y) 
prevx = self.lastx 
prevy = self.lasty 
if self.curFunc: 
self.lastx = curx 
self.lasty = cury 


if self.regular and self.canvas.type('drawing') in \ 


['oval', 'rectangle']: 
dx = self.lastx - self.startx o- 
dy = self.lasty - self.starty 


delta = max(dx, dy) 

self.lastx = self.startx + delta 

self.lasty = self.starty + delta 

self.curFunc(self.startx, self.starty, self.lastx, 
self.lasty, prevx, prevy, self.foreground, 
self.background, self.fillStyle, self.lineWidth, None) 


else: 
if self.selObj: 
self.canvas.move(self.selObj, curx-prevx, cury-prevy) 
self.lastx = curx 
self.lasty = cury 


def mouseUp(self, event): 

self.prevx = self.lastx 

self.prevy = self.lasty 

self.lastx = self.canvas.canvasx(event.x) 

self.lasty = self.canvas.canvasy(event.y) 

if self.curFunc: 

if self.regular and self.canvas.type('drawing') in \ 
['oval', 'rectangle']: 





dx = self.lastx - self.startx 
dy = self.lasty - self.starty 
delta = max(dx, dy) < 
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self.lastx = self.startx + delta 0 
self.lasty = self.starty + delta 
self.curFunc(self.startx, self.starty, self.lastx, 
self.lasty, self.prevx, self.prevy, self.foreground, 
self.background, self.fillStyle, self.lineWidth, 
self.lineData) 
self.storeObject () 
else: 
if self.selObj: 
self.canvas.itemconfig(self.selObj, 
width=self.savedWidth) 


def drawLine(self,x,y,x2,y2,x3,y3,fg,bg,fillp,wid,1ld): 
self.canvas.delete(self.curObject) 
self.curObject = self.canvas.create_line(x,y,x2,y2,fill=fg, 
tags='drawing',stipple=fillp,  width=wid) 


def drawFree(self,x,y,x2,y2,x3,y3,fg,bg,fillp,wid,1d): 
self .drawFreeSmooth(x,y,x2,y2,x3,y3,FALSE, fg,bg, fillp,wid,1d) 


def drawSmooth(self,x,y,x2,y2,x3,y3,fg,bg,fillp,wid, ld): 
self .drawFreeSmooth(x,y,x2,y2,x3,y3,TRUE, fg,bg, fillp, wid, 1d) 


def drawFreeSmooth(self,x,y,x2,y2,x3,y3,smooth,fg,bg,fillp, 
wid, 1d): 
if not: 1d: 
for coord in [[x3, y3, x2, y2], [x2, y2]][smooth]: 
self.lineData. append (coord) 
ild = self.lineData 
else: 
ild = 1d 
if len(ild) > 2: 
self.curObject = self.canvas.create_line(ild, fill=fg, 
stipple=fillp, tags='drawing', width=wid, smooth=smooth) 


def drawRect (self,x,y,x2,y2,x3,y3,fg,bg,fillp,wid,1d): 
self.drawFilledRect (x,y,x2,y2,x3,y3,fg,'',fillp,wid,1d) 


def drawFilledRect (self,x,y,x2,y2,x3,y3,fg,bg,fillp,wid,1d): 
self.canvas.delete(self.curObject) 
self.curObject = self.canvas.create_rectangle(x,y,x2,y2, 
outline=fg, tags='drawing',fill=bg, 
stipple=fillp, width=wid) 


def drawOval (self,x,y,x2,y2,x3,y3,fg,bg,fillp,wid,1d): 
self .drawFilledOval (x,y,x2,y2,x3,y3,fg,'',fillp,wid,1d) 


def drawFilledOval (self,x,y,x2,y2,x3,y3,fg,bg,fillp,wid,1d): 
self.canvas.delete(self.curObject) 
self.curObject = self.canvas.create_oval(x,y,x2,y2,outline=fg, 
fill=bg,tags='drawing',stipple=fillp, width=wid) 





Code comments (continued) 


© Each of the select callbacks uses the tag attached to each of the toolbar buttons to look up the 
function, line width, or other property of a button (Some of the code has been removed). 
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def selectFunc(self, tag): 
self.curFunc = self.func[tag] 
if self.curFunc: 
self.canvas.config(cursor='crosshair' ) 
else: 
self.canvas.config(cursor='arrow' ) 


A cursor is also selected, appropriate for the current operation. 
@ The mouse callbacks are similar to those in the earlier two examples. 


© This code implements the squaring or rounding of rectangles and ovals if the appropriate flags 
have been set. 


© The draw methods are quite similar to earlier examples with the addition of storing a list of 
line segments (for curved lines), smoothing and object attributes. 


draw3.py (continued) 


def storeObject (self): 
self.objects.append(( self.startx, self.starty, self.lastx, 
self.lasty, self.prevx, self.prevy, self.curFunc, D 
self.foreground, self.background, self.fillStyle, 
self.lineWidth, self.lineData )) 


def redraw(self): 
self.canvas.delete (ALL) 
for startx, starty, lastx, lasty, prevx, prevy, func, \ 
fg, bg, fill, lwid, 1d, in self.objects: LO 
self.curObject = None 
func(startx, starty, lastx, lasty, prevx, prevy, 
fg, bg, fill, lwid, 1d) 





def initData(self): 





self.curFunc = self.drawLine 
self.curObject = None 
self.selObj = None 
self.lineData = [] 
self.savedWidth = 1 
self.objects = [] 
self.foreground = 'black' 
self.background = 'white' 
self.fil1Style = None 
self.lineWidth = 1 
self.regular = FALSE 

def ipostscript (self): ® 
postscript = self.canvas.postscript () 
fd = open('drawing.ps', 'w') 
fd.write (postscript) 
fd.close() 


def close(self): 
self.quit() 


def createInterface(self): 
AppShell.AppShell.createInterface (self) 
self.createButtons() 
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self.initData() 
self.createBase() 
self.createTools() 
self.createLineWidths () 
self.createLineColors () 
self.createFillColors() 
self.createPatterns () 


if _name__ == '_main_': 
draw = Draw() 
draw.run() 





Code comments (continued) 


@ The purpose of storeObject is to store a list of object descriptors in the order in which they 
were created, so that the drawing can be refreshed in the correct order. 


@ redraw deletes all of the current objects and recreates them, with all original attributes and tags. 


@ Tk canvases have a wonderful ability to create a PostScript representation of themselves (it is a 
pity that the rest of the widgets cannot do this). As a result, we are able to output a file con- 
taining the PostScript drawing, which can be printed or viewed with the appropriate software. 


10.3 Scrolled canvases 


Frequently, the size of a drawing exceeds the available space on the screen. To provide a larger 
canvas, we must scroll the canvas under a viewing area. Handling scrollbars in some window- 
ing systems (X Window, for example) can require a moderate amount of code. Tkinter (Tk) 
makes scroll operations relatively easy to code. Take a look at this example, which was 
reworked directly from a Tk example. 


Scrolled Canvas 


Figure 10.7 Managing a 
scrolled canvas 
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cscroll.py 


from Tkinter import * 


class ScrolledCanvas: 
def __ init__(self, master, width=500, height=350): 

Label (master, text="This window displays a canvas widget " 
"that can be scrolled either using the scrollbars or " 
"by dragging with button 3 in the canvas. If you " 
"click button 1 on one of the rectangles, its indices " 
"will be printed on stdout.", 
wraplength="4i", justify=LEFT) .pack(side=TOP) 

self.control=Frame (master) 

self.control.pack(side=BOTTOM, fill=X, padx=2) 

Button(self.control, text='Quit', command=master.quit) .pack() 





self.grid = Frame (master) 

self.canvas = Canvas(master, relief=SUNKEN, borderwidth=2, 
scrollregion=('-1l1lc', '-11c', '50c', '20c')) 
self.hscroll = Scrollbar(master, orient=HORIZONTAL, 
command=self.canvas.xview) 

self.vscroll = Scrollbar(master, command=self.canvas.yview) 





self.canvas.configure(xscrollcommand=self.hscroll.set, 
yscrollcommand=self.vscroll.set) 


self.grid.pack(expand=YES, fill=BOTH, padx=1, pady=1) 
self.grid.rowconfigure(0, weight=1, minsize=0) 
self.grid.columnconfigure(0, weight=1, minsize=0) 
self.canvas.grid(padx=1, in_=self.grid, pady=1, row=0, 

column=0, rowspan=1, columnspan=1, sticky='news') 
self.vscroll.grid(padx=1, in_=self.grid, pady=1, row=0, 

column=1, rowspan=1, columnspan=1, sticky='news') 
self.hscroll.grid(padx=1, in_=self.grid, pady=1, row=1, 

column=0, rowspan=1, columnspan=1, sticky='news' ) 
self.oldFill = None 





bg = self.canvas['background' ] 
for i in range(20): 
x = -10 + 3*i 
y = -10 
for j in range(10): 
self.canvas.create_rectangle ('%dc'%x, '%dc'%y, 

















'"Sdc'S(x+2), 'Sdc'S(y+2), outline='black', 
fill=bg, tags='rect') 
self.canvas.create_text('%$dc'%(x+1), '%dc'%S(y+1), 
text='%d,%d'%(i,j), anchor=CENTER, 
tags=('text', 'rect')) 
y=ayHt3 
self.canvas.tag_bind('rect', '<Any-Enter>', self.scrollEnter) 
self.canvas.tag_bind('rect', '<Any-Leave>', self.scrollLeave) 
( 


self.canvas.bind_all('<1>', self.scrollButton) 
self.canvas.bind('<3>', 

lambda e, s=self: s.canvas.scan_mark(e.x, e.y)) 
self.canvas.bind('<B3-Motion>', 

lambda e, s=self: s.canvas.scan_dragto(e.x, e.y)) 
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def scrollEnter(self, event): 
id = self.canvas.find_withtag (CURRENT) [0] 
if 'text' in self.canvas.gettags (CURRENT) : 
id = id-1 
self.canvas.itemconfigure(id, fill='SeaGreen1' ) 


def scrollLeave(self, event): 
id = self.canvas.find_withtag (CURRENT) [0] 
if 'text' in self.canvas.gettags (CURRENT) : 
id = id-1 
self.canvas.itemconfigure(id, fill=self.canvas ['background']) 


def scrollButton(self, event): 
ids = self.canvas.find_withtag (CURRENT) 


if ids: 
id = ids[0] 
if not 'text' in self.canvas.gettags (CURRENT) : 


id = id+1 
print 'You clicked on %s' % \ 
self.canvas.itemcget(id, 'text') 


if _ name_ == '_main_': 
root = Tk() 
root.option_add('*Font', 'Verdana 10') 


root.title('Scrolled Canvas' ) 
scroll = ScrolledCanvas (root) 
root .mainloop () 





Code comments 


@ We create the canvas with a 61cm x 31cm scroll region which clearly will not fit in a 500x 350 
(pixels) window. The horizontal and vertical bars are created and bound directly to the posi- 
tion method of the canvas. 


self.canvas = Canvas(master, relief=SUNKEN, borderwidth=2, 
scrollregion=('-11ic', '-1l1lc', '50c', '20c')) 
self.hscroll = Scrollbar(master, orient=HORIZONTAL, 
command=self.canvas.xview) 
self.vscroll = Scrollbar(master, command=self.canvas.yview) 
@ The scroll bars are set to track the canvas: 


self.canvas.configure(xscrollcommand=self.hscroll.set, 


yscrollcommand=self.vscroll.set) 
© Setting up the bindings to pan the canvas when the right mouse button is clicked and dragged 
is surprisingly easy—we just bind the click to the scan_mark method and the drag to 
scan_dragto. 
self.canvas.bind('<3>', 
lambda e, s=self: s.canvas.scan_mark(e.x, e.y) ) 
self.canvas.bind('<B3-Motion>', 
lambda e, s=self: s.canvas.scan_dragto(e.x, e.y)) 
© Finally, the serol1Button callback is worthy of a brief note. It illustrates the ease of using 
tags to identify objects: 
ids = self.canvas.find_withtag (CURRENT) 
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if ids: 


id = ids[0] 
if not 'text' in self.canvas.gettags (CURRENT) : 
id = id+1 


print 'You clicked on %s' % \ 
self.canvas.itemcget(id, '‘text') 
First we find all the ids with the CURRENT tag (this will be either the rectangle or the text 
field at its center). We only care about the first tag. 
Then, we check to see if it is the text object. If it is not, the next id will be the text 
object, since we defined the rectangle first. 
Last, we get the text object’s contents which give the row-column coordinates. 


10.4 Ruler-class tools 


Another common drawing tool is a ruler. This can be used to provide tab stops or other con- 
straint graphics. It also illustrates some of the aspects of drag-and-drop from within an appli- 
cation. This example was also recoded from a Tk example. 


Ruler 





Figure 10.8 A simple ruler tool 


from Tkinter import * 





class Ruler: 
def _ init_ (self, master, width='14.8c', height='2.5c'): 
Label (master, text="This canvas widget shows a mock-up of a " 
"ruler. You can create tab stops by dragging them out " 
"of the well to the right of the ruler. You can also " 
"drag existing tab stops. If you drag a tab stop far " 
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"enough up or down so that it turns dim, it will be " 
"deleted when you release the mouse button.", 
wraplength="5i", justify=LEFT) .pack(side=TOP) 
self.ctl=Frame (master) 
self.ctl.pack(side=BOTTOM, fill=X, padx=2, pady=2) 
Button(self.ctl, text='Quit', command=master.quit) .pack() 
self.canvas = Canvas(master, width=width, height=height, 
relief=FLAT, borderwidth=2) 
self.canvas.pack(side=TOP, £111=X) 





c = self.canvas 

self.grid = '0.25c' 

self.left = c.winfo_fpixels('1c') 
self.right = c.winfo_fpixels('13c') 
self.top = c.winfo_fpixels('1c') 
self.bottom = c.winfo_fpixels('1.5c') 
self.size = c.winfo_fpixels('.2c') 
self.normalStyle = 'black' 
self.activeStyle = 'green' 
self.activeStipple = '' 
self.deleteStyle = 'red' 
self.deleteStipple = 'gray25' 


e.create_line("1le", "0.5e%; ‘ler, ‘le, 1130", ‘Les, on 
'13c', '0.5c', width=1) 
for i in range(12): 
x = itl 
c.create_line('%dc'%x, 'lc', '%dc'%x, '0.6c', width=1) 
c.create_line('%d.25c'%x, ‘1lc', '%d.25c'%x, 
'0.8c', width=1) 
c.create_line('%d.5c'%x, '1c', '%d.5c'%x, 
'0.7c', width=1) 
c.create_line('%d.75c'%x, ‘1lc', '%d.75c'%x, 
'0.8c', width=1) 
c.create_text ('%d.15c'%x, '.75c', text=i, anchor=SW) 


wellBorder = c.create_rectangle('13.2c', ‘lc', '13.8c', 
'0.5c', outline='black', 
fill=self.canvas['background' ] ) 
wellTab = self.mkTab(c.winfo_pixels('13.5c'), 
c.winfo_pixels('.65c')) 
c.addtag_withtag('well', wellBorder) 
c.addtag_withtag('well', wellTab) 


c.tag_bind('well', '<1>', 
lambda e, s=self: s.newTab(e.x, e.y)) 
c.tag_bind('tab', Velo, 


lambda e, s=self: s.selectTab(e.x, e.y)) 
c.bind('<B1l-Motion>', 

lambda e, s=self: s.moveTab(e.x, e.y)) 
c.bind('<Any-ButtonRelease-1>', self.releaseTab) 


def mkTab(self, x, y): 


return self.canvas.create_polygon(x, y, x+self.size, 
ytself.size, x-self.size, y+tself.size) 
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def newTab(self, x, y): 
newTab = self.mkTab(x, y) 
self.canvas.addtag_withtag('active', newTab) |e 
self.canvas.addtag_withtag('tab', newTab) 
self.x = x 
self.y = y 
self.moveTab(x, y) 


def selectTab (self, x, y): 
self.x = self.canvas.canvasx(x, self.grid) 
self.y = self.top + 2 
self.canvas.addtag_withtag('active', CURRENT) 
self.canvas.itemconfig('active', fill=self.activeStyle, 
stipple=self.activeStipple) 
self.canvas.lift('active') 





def moveTab(self, x, y): | © 
tags = self.canvas.find_withtag('active') 
if not tags: return 
cx = self.canvas.canvasx(x, self.grid) O 
cy = self.canvas.canvasx(y) 
if cx < self.left: 
cx = self.left 
if cx > self.right: 
cx = self.right 
if cy >= self.top and cy <= self.bottom: 
cy = self.top+2 
self.canvas.itemconfig('active', fill=self.activeStyle, 
stipple=self.activeStipple) 
else: 
cy = cy-self.size-2 
self.canvas.itemconfig('active', fill=self.deleteStyle, 
stipple=self.deleteStipple) 
self.canvas.move('active', cx-self.x, cy-self.y) 
self.x = cx 
self.y = cy 


def releaseTab(self, event): 
tags = self.canvas.find_withtag('active') 
if not tags: return 
if self.y != self.top+2: 
self.canvas.delete('active') 


bvb) «Ss 26 





else: 
self.canvas.itemconfig('active', fill=self.normalStyle, 
stipple=self.activeStipple) 
self.canvas.dtag('active') 
__name__ == '_ main__': 
root = Tk() 
root.option_add('*Font', 'Verdana 10') 


root.title('Ruler') 
ruler = Ruler(root) 
root.mainloop() 
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Code comments 


This example illustrates how dimensions may be specified in any valid Tkinter distance and 
converted to pixels (in this case as a floating point number), 
self.right = c.winfo_fpixels('13c') 
Similarly, we can create an object using absolute measurements (in this case, centimeters). 
This can be useful if you are working directly from a drawing and you have a ruler! 

c.create_line('1ec', '0.5¢c', 'le', '1le', '13c', ‘1le', 

'13c', '0.5c', width=1) 

Tkinter sometimes hides the capability of the underlying Tk function. In this case we are add- 
ing two tags, active and tab, to the newly-created object newTab. 


newTab = self.mkTab(x, y) 
self.canvas.addtag_withtag('active', newTab) 
self.canvas.addtag_withtag('tab', newTab) 
The addtag_withtag method hides the fact that the withtag argument applies to 
both tags and ids, which are being passed here. 


moveTab has a lot of work to do, since the user can create new tabs, as well as move and delete 
existing ones. If I weren't following Ousterhout’s example, I would probably reduce the com- 
plexity here. 
The ruler arranges to snap the tab to the nearest 0.25 cm (self.grid). The canvasx 
method takes an optional argument, which defines the resolution with which the conversion 
to canvas coordinates is to be made. 
cx = self.canvas.canvasx(x, self.grid) 
If the pointer moves between the top and bottom range of the ruler, we snap the vertical posi- 
tion of the tab and fill it with a distinctive color so that it is readily identified. 
cy = self.top+2 
self.canvas.itemconfig('active', £fill=self.activeStyle, 
stipple=self.activeStipple) 
If we have moved outside the bounds of top and bottom, we push it out further and fill it 
with a distinctive color stippling so that it becomes a ghost. 
cy = cy-self.size-2 
self.canvas.itemconfig('active', £fill=self.deleteStyle, 
stipple=self.deleteStipple) 
As with moving the tab, releasing it requires multiple actions. 


If the tab is marked for deletion (it isn’t at the snapped-to y-value) the object is deleted. 
if self.y != self.top+2: 
self.canvas.delete('active') 
Otherwise, we fill the tab with a normal color and delete the active tag. 


self.canvas.itemconfig('active', £ill=self.normalStyle, 
stipple=self.activeStipple) 
self.canvas.dtag('active' ) 
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10.5 Stretching canvas objects 


A common operation for drawing programs is stretching an existing object. This requires us 
to provide grab handles which the user can click and drag to resize the object. Before we add 
resize operations to our drawing example, let’s take a look at a slightly simpler example which 
was also converted from Tk. This little program allows you to experiment with the two 
attributes that determine the shape of an arrow, width and arrowshape. You might find this 
a useful tool if you ever want to create arrows with a distinctive shape. 
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Arrow Editor (- [of x] 


This widget allows you to experiment with different widths and 
arrowhead shapes for lines in canvases. To change the line width or 
the shape of the arrowhead, drag any of the three boxes attached to 
the oversized arrow. The arrows on the right give examples at normal 
scale. The text at the bottom shows the configuration options as 
you'd enter them for a canvas line item. 


Arrow Editor [-lolxl 


This widget allows you to experiment with different widths and 
arrowhead shapes for lines in canvases. To change the line width or 
the shape of the arrowhead, drag any of the three boxes attached to 
the oversized arrow. The arrows on the right give examples at normal 
scale, The text at the bottom shows the configuration options as 
you'd enter them for a canvas line item. 





width=2 
arrowshape=(8,10,3) 


Quit 


width=2 
arrowshape=(8,10,4) 


Quit 





Arrow Editor [-lolxl 


This widget allows you to experiment with different widths and 
arrowhead shapes for lines in canvases. To change the line width or 
the shape of the arrowhead, drag any of the three boxes attached to 
the oversized arrow. The arrows on the right give examples at normal 
scale. The text at the bottom shows the configuration options as 


2 


Arrow Editor [-lolxl 


This widget allows you to experiment with different widths and 
arrowhead shapes for lines in canvases. To change the line width or 
the shape of the arrowhead, drag any of the three boxes attached to 
the oversized arrow. The arrows on the right give examples at normal 
scale, The text at the bottom shows the configuration options as 





you'd enter them for a canvas line item. 


width=2 
arrowshape=(8,8,6) 


Quit 
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Figure 10.9 Stretching canvas objects 
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you'd enter them for a canvas line item. 


width=2 
arrowshape=(10,8,6) 


Quit 
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from Tkinter 





import * 


class ArrowEditor: 


def __init__(self, master, 
Label (master, 


self. 
self. 
Button (self 
self. 


self. 


self. 
self. 
self. 
self. 
self. 
self. 
self. 
self. 
self. 
self. 
self. 
self. 


self. 
self. 


self. 
self. 
self. 
self. 
self. 


self. 


def motion(self, 
self. 
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width=500, height=350): 

text="This widget allows you to experiment " 
"with different widths and arrowhead shapes for lines " 
"in canvases. To change the line width or the shape " 
"of the arrowhead, drag any of the three boxes " 
"attached to the oversized arrow. The arrows on the " 
"right give examples at normal scale. The text at " 
"the bottom shows the configuration options as you'd " 
"enter them for a canvas line item.", 

wraplength="5i", justify=LEFT) .pack(side=TOP) 

control=Frame (master) 

control.pack(side=BOTTOM, f£i11=X, padx=2) 

.control, text='Quit', command=master.quit) .pack() 

Canvas(master, width=width, height=height, 
relief=SUNKEN, borderwidth=2) 

.pack(expand=YES, f£i11=BOTH) 


canvas 





canvas 


8 
10 


a 
b 
c 3 
width= 2 
motionProc 
x1 40 
w2 = 350 
y 150 
smallTips= (5,5,2) 
bigLine= 'SkyBlue2' 
boxFill= '' 
activeFill = 


# Setup default values 


None 


'red' 


arrowSetup () # Draw default arrow 
canvas.tag_bind('box', '<Enter>', lambda e, s=self: 
s.canvas.itemconfig(CURRENT, fill='red')) 
canvas.tag_bind('box', '<Leave>', lambda e, s=self: 
s.canvas.itemconfig(CURRENT, fill='')) 
tag_bind('box1', '<1>', lambda e, s=self: 
s.motion(s.arrowMovel1) ) 
tag_bind('box2', '<1>', lambda e, 
s.motion(s.arrowMove?2) ) 
.tag_bind('box3', '<1>', lambda e, 
s.motion(s.arrowMove3) ) 
tag_bind('box', '<Bl-Motion>', 
s=self: s.motionProc(e) ) 
.bind('<Any-ButtonRelease-1>', 
s=self: s.arrowSetup() ) 





canvas. 
canvas. s=self: 
canvas s=self: 
canvas. lambda e, 


canvas lambda e, 





func): 
motionProc 


func 
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def arrowMovel(self, event): 
newA = (self.x2+5-int(self.canvas.canvasx(event.x)))/10 
if newA < 0: newA = 0 
if newA > 25: newA = 25 
if newA != self.a: 
self.canvas.move("box1", 10*(self.a-newA), 0) 
self.a = newA 


def arrowMove2(self, event): 
newB = (self.x2+5-int(self.canvas.canvasx(event.x)))/10 
if newB < 0: newB = 0 
if newB > 25: newB = 25 
newC = (self.y+5-int(self.canvas.canvasx(event.y)+ \ 
5*self.width) )/10 
if newC < 0: newC = 0 
if newC > 20: newC = 20 
if newB != self.b or newC != self.c: 
self.canvas.move("box2", 10* (self.b-newB) , 
10* (self.c-newC) ) 
self.b = newB 
self.c = newC 


def arrowMove3 (self, event): 
newW = (self.y+2-int (self.canvas.canvasx(event.y)))/5 
if newwW < 0: newW = 0 
if newwW > 20: newW = 20 
if newW != self.width: 
self.canvas.move("box3", 0, 5*(self.width-neww) ) 
self.width = newW 


def arrowSetup(self): 
tags = self.canvas.gettags (CURRENT) 
cur = None 
if 'box' in tags: 
for tag in tags: 
if len(tag) == 4 and tag[:3] == 'box': 
cur = tag 
break 
self.canvas.delete (ALL) 
self.canvas.create_line(self.xl, self.y, self.x2, self.y, 
width=10*self.width, 
arrowshape=(10*self.a, 10*self.b, 10*self.c), 
arrow='last', fill=self.bigLine) 
xtip = self.x2-10*self.b 
deltay = 10*self.c+5*self.width 
self.canvas.create_line(self.x2, self.y, xtip, self.y+deltayY, 
self.x2-10*self.a, self.y, xtip, self.y-deltayY, 
self.x2, self.y, width=2, capstyle='round', 
joinstyle='round' ) 
self.canvas.create_rectangle(self.x2-10*self.a-5, self.y-5, 
self.x2-10*self.a+5, self.y+5, 
fill=self.boxFill, outline='black', 
tags=('boxl', 'box')) 
self.canvas.create_rectangle(xtip-5, self.y-deltayY-5, 
xtip+5, self.y-deltaY+5, 
fill=self.boxFill, outline='black', 
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tags=('box2', 'box')) 
self.canvas.create_rectangle(self.x1-5, 
self.y-5*self.width-5, self.x1+5, 
self.y-5*self.width+5, fill=self.boxFill, 
outline='black', tags=('box3', 'box')) 
if cur: 
self.canvas.itemconfig(cur, fill=self.activeFill) 
self.canvas.create_line(self.x2+50, 0, self.x2+50, 
1000, width=2) 


tmp = self.x2+100 

self.canvas.create_line(tmp, self.y-125, tmp, self.y-75, 
width=self.width, arrow='both', 
arrowshape=(self.a, self.b, self.c)) 

self.canvas.create_line(tmp-25, self.y, tmp+25, self.y, 
width=self.width, arrow='both', 
arrowshape=(self.a, self.b, self.c)) 

self.canvas.create_line(tmp-25, self.y+75, tmp+25, self.y+125, 
width=self.width, arrow='both', 
arrowshape=(self.a, self.b, self.c)) 


tmp = self.x2+10 
self.canvas.create_line(tmp, self.y-5*self.width, tmp, 
self.y-deltaY, arrow='both', arrowshape=self.smallTips) 
self.canvas.create_text (self.x2+15, self.y-deltaY+5*self.c, 
text=self.c, anchor=W) 
tmp = self.x1-10 
self.canvas.create_line(tmp, self.y-5*self.width, tmp, 
self.y+5*self.width, arrow='both', 
arrowshape=self.smallTips) 
self.canvas.create_text(self.x1-15, self.y, 
text=self.width, anchor=E) 
tmp = self.y+5*self.width+10*self.c+10 
self.canvas.create_line(self.x2-10*self.a, tmp, self.x2, tmp, 
arrow='both', arrowshape=self.smallTips) 
self.canvas.create_text(self.x2-5*self.a, tmp+5, 
text=self.a, anchor=N) 
tmp = tmp+25 
self.canvas.create_line(self.x2-10*self.b, tmp, self.x2, tmp, 
arrow='both', arrowshape=self.smallTips) 
self.canvas.create_text(self.x2-5*self.b, tmp+5, 
text=self.b, anchor=N) 


self.canvas.create_text(self.x1, 310, text="width=%d" % \ 
self.width, anchor=W, font=('Verdana', 18) 
self.canvas.create_text(self.x1, 330, 
text="arrowshape=(%d,%d,%d)" % \ 
(self.a, self.b, self.c), 
anchor=W, font=('Verdana', 18) ) 


) 


if _ name == '_main_': 
root = Tk() 
root.option_add('*Font', 'Verdana 10') 





root.title('Arrow Editor') 
arrow = ArrowEditor (root) 
root.mainloop() 
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Code comments 


@ This example has to create many bindings: 





1 An <Enter> callback to color the grab handle. 

2 A <Leave> callback to remove the added color. 

3 A <Button-1> (<1>) callback for each of the grab handles. 

4 A<B1-Motion> callback for a common callback for each of the grabs. 

5 An <Any-ButtonRelease-1> callback to process the final location of the grab. 


@ The responsibility of each of the three arrowMove methods is to validate that the value is 
within bounds and then draw the grab at the current location. 


© Since we have three separate boxes (box1, box2 and box3) we need to implement a simple 
search algorithm within the tags to determine which box created the event: 
if 'box' in tags: 
for tag in tags: 
if len(tag) == 4 and tag[:3] == 'box': 
cur = tag 
break 


© We then create a line using the supplied width and the appropriate arrowshape values. 


The remainder of the code is responsible for updating the values of the dimensions on 
the screen and drawing the example arrows. Since this example illustrates 1-to-1 translation of 
Tk to Tkinter, I have not attempted to optimize the code. I am certain that some of the code 
can be made more succinct. 


10.6 Some finishing touches 


We are going to extend the capability of draw3.py to add some additional functionality and 
provide some features that may be useful if you use this example as a template for your own 


code. This is what has been added: 
1 Menu options to create New drawings and Open existing ones. 
2 A Menu option to save drawings with a supplied filename (Save As). 
3 A Menu option to save an existing drawing to its file (Save). 
4 A Move operation to allow an object to be moved about the canvas. 
5 Stretch operations with eight grab handles. 
The following code example is derived from draw3.py, which was presented on page 245. 


I have removed much of the common code, so that this example is not too long, but note that 
this example has a Jot to do! 


draw4.py 


from Tkinter import * 

import Pmw, AppShell, math, time, string, marshal 
from cursornames import * 

from toolbarbutton import ToolBarButton | 9 
from tkFileDialog import * 


262 CHAPTER 10 DRAWING BLOBS AND RUBBER LINES 











Drawing Program - Version 4 x Drawing Program - Version 4 

















Figure 10.10 Adding movement and stretching to the drawing program 


transDict = { 'bx': 'boundx', 'by': 'boundy', 
'x': 'adjx', 'y': ‘tadjy', 
nos ‘uniqueIDINT' } 


class Draw(AppShell.AppShell) : 
# --- Code Removed ------------------------------------------------------ 


def createMenus (self): 

self .menuBar .deletemenuitems ('File') 

self.menuBar.addmenuitem('File', 'command', 'New drawing', 
label='New', command=self.newDrawing) 

self.menuBar.addmenuitem('File', 'command', 'Open drawing', 
label='Open...', command=self.openDrawing) 

self.menuBar.addmenuitem('File', 'command', 'Save drawing', 
label='Save', command=self.saveDrawing) 

self.menuBar.addmenuitem('File', 'command', 'Save drawing', 
label='SaveAs...', command=self.saveAsDrawing) 

self.menuBar.addmenuitem('File', 'separator') 
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self .menuBar.addmenuitem('File', 'command', 'Exit program', 
label='Exit', command=self.quit) 


def createTools(self): 


self.func = {} 
self.transFunc = {} (3) 
ToolBarButton (self, self.toolbar, 'sep', 'sep.gif', 


width=10, state='disabled') 
for key, func, balloon in [ 
('pointer', None, 'Edit drawing'), 





('draw', self.drawFree, 'Draw freehand'), 
('smooth', self.drawSmooth, 'Smooth freehand'), 
('line', self.drawLine, 'Rubber line'), 

('rect', self.drawRect, ‘Unfilled rectangle'), 
('frect', self.drawFilledRect, 'Filled rectangle'), 
(toval', self.drawOval, ‘Unfilled oval'), 
('foval', self.drawFilledOval, 'Filled oval')]: 


o 


ToolBarButton (self, self.toolbar, key, '%s.gif' % key, 
command=self.selectFunc, balloonhelp=balloon, 
statushelp=balloon) 


self. func [key] = func 
self.transFunc [func] = key 
Pene Gode Removed = n nr aa n a a a a A A A 





Code comments 
@ The ToolBarButton class has been moved to a separate module. 


@  transDict is going to be used when we parse the tags assigned to each of the grab handles. 
See @ below. 


© transFunc is created as a reverse-lookup, so that we can find the key associated with a partic- 
ular function. 


draw4.py (continued) 


def mouseDown(self, event): 
self.curObject = None 
self.canvas.dtag('drawing' 
self.lineData = [] 
self.lastx = self.startx = self.canvas.canvasx(event.x) 
self.lasty = self.starty = self.canvas.canvasy(event.y) 
self.uniqueID = 'S*%d' % self.serial 
self.serial = self.serial + 1 


if not self.curFunc: 
if event.widget.find_withtag (CURRENT) : 

tags = self.canvas.gettags (CURRENT) 

for tag in tags: 
if tag[:2] == 'S*': 

objectID = tag 

if 'grabHandle' in tags: 
self.inGrab = TRUE 
self.releaseGrab = FALSE 
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self.uniqueID = objectID 
else: 
self.inGrab = FALSE 
self.addGrabHandles(objectID, 'grab') 
self .canvas.config(cursor='fleur' ) 
self.uniqueID = objectID 
else: 

self.canvas.delete("grabHandle") 

self .canvas.dtag("grabHandle") 

self.canvas.dtag("grab") 


def mouseMotion(self, event): 
curx = self.canvas.canvasx(event.x) 
cury = self.canvas.canvasy(event.y) 
prevx = self.lastx 
prevy = self.lasty 
if not self.inGrab and self.curFunc: 
self.lastx = curx 
self.lasty = cury 
if self.regular and self.curFunc in \ 
[self.func['oval'], self.func['rect'], 
self.func['foval'],self.func['frect']]: 
dx = self.lastx - self.startx 
dy = self.lasty - self.starty 
delta = max(dx, dy) 
self.lastx = self.startx + delta 
self.lasty = self.starty + delta 
self.curFunc(self.startx, self.starty, self.lastx, 
self.lasty, prevx, prevy, self.foreground, 
self.background, self.fillStyle, self.lineWidth, None) 
elif self.inGrab: 
self.canvas.delete("grabbedObject") 
self .canvas.dtag("grabbedObject") 
tags = self.canvas.gettags (CURRENT) 
for tag in tags: 
if '*' in tag: 
key, value = string.split(tag, '*') 
var = transDict [key] 
setattr(self, var, string.atoi(value) ) 
self.uniqueID = 'S*%d' % self.uniqueIDINT 
x1, yl, x2, y2, px, py, self.growFunc, \ 
fg, bg, fill, lwid, ld= self.objects[self.uniqueID] 


if self.boundx == 1 and self.adjx: O 
x1 = x1 + curx-prevx 

elif self.boundxX == 2 and self.adjx: 
x2 = x2 + curx-prevx 

if self.boundy == 1 and self.adjyY: 
yl = yl + cury-prevy 

elif self.boundY == 2 and self.adjyY: 


y2 = y2 + cury-prevy 
self .growFunc (x1,y1,x2,y2,px,py,fg,bg, fill, 1lwid,1d) 
self.canvas.addtag_withtag("grabbedObject", 
self .uniqueID) 
self.storeObject (x1,y1,x2,y2,px,py,self.growFunc, 
fg,bg, £il11,1lwid,1d) Vv 
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self.lastx = curx 
self.lasty cury 
else: 
self.canvas.move('grab', curx-prevx, cury-prevy) 
self.lastx = curx 
self.lasty = cury 


def mouseUp(self, event): 
self.prevx = self.lastx 
self.prevy = self.lasty 
self.lastx = self.canvas.canvasx(event.x) 
self.lasty = self.canvas.canvasy(event.y) 
if self.curFunc: 
if self.regular and self.curFunc in \ 
[self.func['oval'], self.func['rect'], 
self.func['foval'],self.func['frect']]: 
dx = self.lastx - self.startx 
dy = self.lasty - self.starty 
delta = max(dx, dy) 
self.lastx = self.startx + delta 
self.lasty = self.starty + delta 
self.curFunc(self.startx, self.starty, self.lastx, 
self.lasty, self.prevx, self.prevy, self.foreground, 
self.background, self.fillStyle, self.lineWidth, 
self.lineData) 
self.inGrab = FALSE 
self.releaseGrab = TRUE 
self.growFunc = None 
self.storeObject(self.startx, self.starty, self.lastx, o 
self.lasty, self.prevx, self.prevy, self.curFunc, 
self.foreground, self.background, self.fillStyle, 
self.lineWidth, self.lineData) 
else: 
if self.inGrab: 
tags = self.canvas.gettags (CURRENT) 
for tag in tags: 
if '*' in tag: 
key, value = string.split(tag, '*') 
var = transDict [key] 
setattr(self, var, string.atoi(value) ) O 
x1,y1,x2,y2, px, py, self.growFunc, \ 
fg,bg,£i11,lwid,1d = self.objects[self.uniqueID] 
if self.boundX == 1 and self.adjx: 
xl = x1 + self.lastx-self.prevx 
elif self.boundx == 2 and self.adjx: 
x2 = x2 + self.lastx-self.prevx 
if self.boundy == 1 and self.adjyY: 
y1 = yl + self.lasty-self.prevy 
elif self.boundy == 2 and self.adjy: 
y2 = y2 + self.lasty-self.prevy 
self .growFunc (x1,y1,x2,y2,px,py,f£g,bg,£il1l1,1wid,1d) 
self.storeObject (x1,y1,x2,y2,px, py, self£.growFunc, 
fg,bg,f£i11,1lwid,1d) 
self .addGrabHandles(self.uniqueID, self.uniqueID) 
if self.selObj: 
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self.canvas.itemconfig(self.selObj, 
width=self.savedWidth) 
self.canvas.config(cursor='arrow' ) 


def addGrabHandles(self, objectID, tag): 
self.canvas.delete("grabHandle") 
self .canvas.dtag("grabHandle") LO 
self.canvas.dtag("grab") 
self .canvas.dtag("grabbedObject") 


self.canvas.addtag("grab", "withtag", CURRENT) 
self.canvas.addtag("grabbedObject", "withtag", CURRENT) 
x1,y1,x2,y2 = self.canvas.bbox(tag) 

for x,y, curs, tagBx, tagBy, tagX, tagY in [ 


(x1,y1,TLC, "bx*1', 'by*1','x*1','y*1'), 
(x2,y1,TRC, "bx*2', 'by*1','x*1','y*1'), 
(x1,y2,BLC, "bx*1', 'by*2','x*1','y*1'), 
(x2,y2,BRC, "bx*2', 'by*2','x*1','y*1'), 


(x1+ ((x2-x1)/2),y1,TS, '"bx*0', 'by*1','x*0','y*1'), 
(x2,y1+((y2-y1)/2),RS, 'bx*2', 'by*0','x*1','y*0'), 
(x1,y1+((y2-y1)/2),LS, 'bx*1', 'by*0', 'x*1', 'y*0"'), D 
(x1+ ( (x2-x1)/2),y2,BS, 'bx*0','by*2','x*0','y*1')]: 
ghandle = self.canvas.create_rectangle(x-2,y-2,x+2,y+2, 
outline='black', fill='"black', tags=('grab', 
'grabHandle', tagBx, tagBy, tagX, 
tagY, '%s'%objectID) ) 
self.canvas.tag_bind(ghandle, '<Any-Enter>', 
lambda e, s=self, c=curs: s.setCursor(e,c) ) 
self.canvas.tag_bind(ghandle, '<Any-Leave>', 
self.resetCursor) 
self.canvas.1lift ("grab") 





#2 (COde+/REMO VER ses ee rg Sa ae oat ee e 





Code comments (continued) 


Each of the objects drawn on the canvas is identified by a unique identity, which is attached 
to the object as a tag. Here we construct an identity: 
self.uniqueID = 'S*%d' % self.serial 
self.serial = self.serial + 1 
Here we use the tags to get the identity of a drawn object from one of the grab handles or the 
object itself: 
for tag in tags: 
if tag[:2] == 'S*':; 
objectID = tag 
Then, we determine if we have grabbed a grab handle (which all contain a grabhandle 
tag) or an object, in which case we change the cursor to indicate that the object is moveable. 


This is where we parse the tags attached to the grab handles. The grab handles are encoded 
with information about their processing; this reduces the amount of code needed to support 
stretching the objects. The tags are attached in step @ below. 


for tag in tags: 
Tf 1s" “in tags 
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key, value = string.split(tag, '*') 
var = transDict [key] 
setattr(self, var, string.atoi(value) ) 

This requires a little more explanation. Take a look at figure 10.11. Each of the grab han- 
dles at the four corners modifies the bounding box. The x- or y-value is associated with either 
BB1 or BB2. So, for example, the bottom-left grab handle is tagged with bx*1 and by*2. 
Additionally, the four median grab handles are constrained to stretch one side of the bound- 
ing box at a time, so we encode (as a boolean value) the axis that is free (x*1 y*0 indicates 
that the x-axis is free). 


Since we need to know the current dimensions of an object’s bounding box as we grow or 
move the object, we store that data each time the callback is invoked. 

When the mouse is released, we have to recalculate the bounding box and store the object’s 
data. This code is similar to the code for mouse movement shown in @. 


In addGrabHandles we begin by removing all existing grab handles from the display, along 
with the associated tags. 


© © O © 


To construct the grab handles, we first get the current bounding box. Then we construct the 
handles using data contained in a list. The tags are constructed to provide the associations 
noted in step @ above. 


affects x2 and y1 







BB1 


affects x1 and y1 


affects x1 only 


BB2 


affects x1 and y2 affects y2 only 


Figure 10.11 Grab handles and their association with the bounding-box coordinates 


draw4.py (continued) 


xl,yl1,x2,y2 = self.canvas.bbox(tag) 

for x,y, curs, tagBx, tagBy, tagX, tagY in [ 
(xl,y1,TLC, (DRED by eae! VaR oR eis 
(x2,y1,TRC, DRAA IDAT sek ORD eg 


---- code removed ----- 
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ghandle = self.canvas.create_rectangle(x-2,y-2,x+2,y+2, 
outline='black', fill='black', tags=('grab', 


‘grabHandle','%s'%tagBx, 's'%tagBy, '%s'%tagX, 
'Ss'StagY, '%s'SobjectID) ) 


def storeObject (self, x1,y1,x2,y2,px,py, func, fg,bg,fill,lwid,1d): 
self .objects[self.uniqueID] = ( x1,yl1,x2,y2,px,py,func,fg,bg, 
fill,lwid,ld ) 


def redraw(self): 
self.canvas.delete (ALL) 
keys = self.objects.keys() 
keys.sort () 
for key in keys: 
startx, starty, lastx, lasty, prevx, prevy, func, \ 
fg, bg, fill, lwid , ld= self.objects[key] 
self.curObject = None 
self.uniqueID = key 
func(startx, starty, lastx, lasty, prevx, prevy, 
fg, bg, fill, lwid, 1d) 


def newDrawing (self): 
self.canvas.delete (ALL) 
self.initData() 


def openDrawing (self): 
ofile = askopenfilename(filetypes=[("PTkP Draw", "ptk"), 
("All Files", "*")]) 
if ofile: 
self.currentName = ofile 
self.initData() 
fd = open(ofile) 
items = marshal.load(fd) D 
for i in range(items): 
self.uniqueID, x1,y1,x2,y2,px,py,cfunc, \ 
fg,bg,fill1,lwid,1d = marshal.load(fd) 
self.storeObject (x1,y1,x2,y2,px,py,self.func[cfunc], 
fg,bg,£il1l1,1lwid,1d) 
fd.close() 
self .redraw() 





def saveDrawing(self): 
self .doSave() 


def saveAsDrawing (self): 
ofile = asksaveasfilename(filetypes=[("PTkP Draw", "ptk"), 
("All Files", "*")]) 
if ofile: 
self.currentName = ofile 
self .doSave() 


def doSave (self): 
fd = open(self.currentName, 'w') 
keys = self.objects.keys() 
keys.sort() 
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marshal.dump(len(keys), £d) 
for key in keys: 

startx, starty, lastx, lasty, prevx, prevy, func, \ 

fg, bg, fill, lwid , 1ld= self.objects [key] 
cfunc = self.transFunc [func] 
marshal.dump((key, startx, starty, lastx, lasty, prevx, \ 
prevy, cfunc, fg, bg, fill, lwid , 1d), fd) 

fd.close() 


def initData(self): 
self.curFunc = self.drawLine 
self.growFunc = None 
self.curObject = None 
self.selObj = None 
self.lineData= [] 
self.savedWidth = 1 
self.savedCursor = None 
self.objects = {} # Now a dictionary 
self.foreground = 'black' 
self.background = 'white' 
self.fillStyle = None 
self.lineWidth = 1 
self.serial = 1000 
self.regular = FALSE 
self.inGrab = FALSE 
self.releaseGrab = TRUE 
self.currentName = 'Untitled' 


F Code Removed ennn r ne na a o a hn asaan 





Code comments (continued) 


@ To load an existing file, we use the standard tkFileDialog dialogs to obtain the filename. 
We then unmarshal* the contents of the file to obtain the stored object dictionary and then 
simply redraw the screen. 

fd = open(ofile) 
items = marshal.load(fd) 
for i in range(items): 
self.uniqueID, x1,y1,x2,y2,px,py,cfunc, \ 
fg,bg,fill,lwid,1d = marshal.load(fd) 
self.storeObject (x1,y1,x2,y2,px,py,self.func[cfunc], 
fg,bg, f£il1l1,1lwid,1d) 
Because it is not possible to marshal member functions of classes (self. func), we store 
the key to the function and use the reverse-lookup created in © to obtain the corresponding 
method. 





* Marshaling is a method of serializing arbitrary Python data in a form that may be written and read to 
simple files. Not all Python types can be marshaled and other methods such as pickle or shelve (to store 
a database object) may be used. It is adequate to provide persistence for our relatively simple dictionary. 
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@ dosave implements the writing of the marshaled data to a file. Figure 10.12 illustrates the 
tkFileDialog used to get the file name. Note that the dialogs are native dialogs for the par- 
ticular architecture upon which Tk is running at release 8.0 and above. 


Saven [S My Documents | | Al cl 


a] Draw1.ptk 





File name: JExampled. pth 
Save as type: |PTkP Draw (*ptk] >] Cancel | 
4 


Figure 10.12 Save As dialog 





10.7 Speed drawing 


In general, creating canvas objects is relatively efficient and rarely causes a performance prob- 
lem. However, for very complex drawings, you may notice a delay in drawing the canvas. This 
is particularly noticeable when the display contains a large number of objects or when they 
contain complex line segments. 

One way of improving drawing performance is to draw the canvas as an image. The 
Python Imaging Library, which was introduced briefly in chapter 5 on page 89, has the facility 
to draw directly to a GIF file. We will use this facility to draw a quite challenging image. I 
always found Mandelbrot diagrams, now generally referred to as fractals, fascinating. While I 
was looking at Douglas A. Young’s The X Window System: Programming and Applications with 
Xt, I noticed the fractal on the cover. Here is an adaptation of the fractal in Python, Tkinter 
and PIL. 


fractal.py 


from Tkinter import * 
import Pmw, AppShell, Image, ImageDraw, os 


class Palette: 
def _ init_ (self): 
self.palette = [(0,0,0), (255,255,255) ] 


def getpalette(self): 
# flatten the palette 
palette = [] 
for r, g, b in self.palette: 
palette = palette + [r, g, b] 
return palette 
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def loadpalette(self, 
import random 
for i in range(cells-2): 


self.palette.append ( ( 


cells): 


random.choice(range(0, 255)), # red 
random.choice(range(0, 255)), # green 
random.choice(range(0, 255)))) # blue 
class Fractal (AppShell.AppShell): 

usecommandarea = 1 

appname = 'Fractal Demonstration' 

frameWidth = 780 

frameHeight = 580 


def createButtons (self): 

self.buttonAdd('Save', 
helpMessage='Save current image', 
statusMessage='Write current image as 
command=self.save) 

self.buttonAdd('Close', 
helpMessage='Close Screen', 
statusMessage='Exit', 
command=self.close) 


tout gif"; 


def createDisplay (self): 
self.width = self.root.winfo_width()-10 
self.height self.root.winfo_height ()-95 
self.form = self.createcomponent ('form', () 
Frame, (self.interior ( 
width=self.width, 
height=self.height) 
form.pack(side=TOP, expand=YES, fi11=BOTH) 
im Image.new("P", (self.width, self.height), 
d = ImageDraw. ImageDraw(self.im) 
d.setfill(0) 


, None, 
Vols 
self. 
self. 


self. 
self. 





0) 





self. 


self. 


label self.createcomponent ('label', 
Label, (self.form,),) 


(), None, 


label .pack () 


def initData(self): 


self. 
self. 
self. 
self. 
self. 
self. 
self. 
self. 


depth 
origin -1.4+1.0j 
range 2.0 
maxDistance = 4.0 
ncolors = 256 

rgb = Palette() 
rgb.loadpalette (255) 
save FALSE 


20 


def createImage(self): 


self. 


updateProgress(0, self.height) 


for y in range(self.height): 


“aye 


for x in range(self.width) : 
05 


complex(self.origin.real + \ 


Zz 
k 
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float (x) /float(self.width) *self.range, 
self.origin.imag - \ 
float(y) / float(self.height) *self.range) 
# calculate z = (z +k) * (z + k) over and over 
for iteration in range(self.depth) : 
real_part = z.real + k.real 
imag_part = z.imag + k.imag 
del z 
z = complex(real_part * real_part - imag_part * \ 
imag_part, 2 * real_part * imag_part) 
distance = z.real * z.real + z.imag * z.imag 
if distance >= self.maxDistance: 
cidx = int(distance % self.ncolors) © 
self.pixel(x, y, cidx) 
break 
self.updateProgress (y) 
self.updateProgress(self.height, self.height) 
self.im.putpalette(self.rgb.getpalette() ) 


self.im.save("out.gif") O 
self.img = PhotoImage(file="out.gif") 
self.label['image'] = self.img 


def pixel(self, x, y, color): 
self.d.setink (color) O 
self.d.point((x, y)) 





def save(self): 
self.save = TRUE 
self.updateMessageBar('Saved as "out.gif"') 





def close(self): 
if not self.save: 
os.unlink("out.gif") 
self.quit() 


def createInterface(self): 
AppShell.AppShell.createInterface (self) 
self.createButtons () 
self.initData() 
self.createDisplay () 


if _ name == '_main_': 
fractal = Fractal() 
fractal.root.after(10, fractal.createImage() ) 
fractal.run() 





Code comments 


The Palette class is responsible for creating a random palette (loadpalette) and generating 
an RGB list for inclusion in the GIF image (getpalette). 


We create a new image, specifying pixel mode (P), and we instantiate the ImageDraw class, 
which provides basic drawing functions to the image. We fill the image with black, initially 
with the set fill method. 
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self.im = Image.new("P", (self.width, self.height), 0) 

self.d = ImageDraw. ImageDraw(self.im) 

self.d.set£i1ll(0) 
At the center of the computational loop, we select a color and set the corresponding pixel to 
that color. 


2 


cidx = int(distance % self.ncolors) 
self.pixel(x, y, cidx) 
When complete, we add the palette to the image, save it as a GIF file, and then load the image 
as a Tkinter PhotoImage. 
self.im.putpalette(self.rgb.getpalette() ) 
self.im.save("out.gif") 
self.img = PhotoImage(file="out.gif") 
self.label['image'] = self.img 
The pixel method is very simple. We set the color of the ink and place the pixel at the speci- 
fied x, y coordinate. 
def pixel(self, x, y, color): 
self.d.setink(color) 
self.d.point((x, y)) 


Running fractal.py on a moderately fast workstation will generate an 800X 600 pixel 
image in about 2-3 minutes. If you are interested, you will find slowfractal.py online. This ver- 
sion is written using Tkinter canvas methods and it takes considerably longer to complete. 


ELL Ld 
File 




















Figure 10.13 Generating fractals 
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10.8 Summary 


This is another important chapter for those readers who want to manipulate objects on a 
screen. Whether building a drawing program or a drafting system of a UML editor, the prin- 
ciples are similar and you will find many of the techniques are readily transferable. 

One thing is very important when designing interfaces such as these: think carefully about 
the range of pointing devices that may be used with your program. While it is quite easy to 
drag an object to resize it when you are using a mouse, it may not be as easy if the user has a 
trackball or is using one of the embedded keyboard mouse buttons. 
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Graphs and charts 


11.1 Simple graphs 276 
11.2 A graph widget 279 
11.3 3-D graphs 292 
11.4 Strip charts 296 
11.5 Summary 298 


There was a time when the term graphics included graphs; this chapter reintroduces this mean- 
ing. Although graphs, histograms and pie charts may not be appropriate for all applications, 
they do provide a useful means of conveying a large amount of information to the viewer. 
Examples will include linegraphs, histograms, and pie charts to support classical graphical for- 
mats. More complex graph examples will include threshold alarms and indicators. 


11.1 Simple graphs 


Let’s start by constructing a very simple graph, without trying to make a graph class or 
adding too many features, so we can see how easy it can be to add a graph to an applica- 
tion. We'll add more functionality later. 


simpleplot.py 


from Tkinter import * 
root = Tk() 
root.title('Simple Plot - Version 1') 
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canvas = Canvas(root, width=450, height=300, bg = 'white') 
canvas .pack() 


Button(root, text='Quit', command=root.quit) .pack() 


canvas.create_line(100,250,400,250, width=2) Draw axes 
canvas.create_line(100,250,100,50, width=2) 


for i in range(11): 
x = 100 + (i * 30) 
canvas.create_line(x,250,x,245, width=2) 
canvas.create_text(x,254, text='%d'% (10*i), anchor=N) 


y = 250 - (i * 40) ticks 
canvas.create_line(100,y,105,y, width=2) 
canvas.create_text(96,y, text='%5.1f£'% (50.*i), anchor=E) 


for i in range(6): |e Drawy 


for x,y in [(12, 56), (20, 94), (33, 98), (45, 120), (61, 180), 
(75, 160), (98, 223)]: 
x = 100 + 3*x Draw data 
y = 250 - (4*y)/5 points 
canvas.create_oval (x-6,y-6,x+6,y+6, width=1, 
outline='black', fi11='SkyBlue2') 


root.mainloop () 





Code comments 


@ Here we add the ticks and labels for the x-axis. Note that the values used are hard-coded—we 
have made little provision for reuse! 


for i in range(11): 
x = 100 + (i * 30) 
canvas.create_line(x,250,x,245, width=2) 
canvas.create_text(x,254, text='%d'% (10*i), anchor=N) 


Notice how we have set this up to increment x in units of 10. 


Simple Plot - Version 1 - (ol x} 





“oO 10 20 30 40 50 60 70 80 90 100 


Figure 11.1 Simple two- 
dimensional graph 
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This small amount of code produces an effective graph with little effort as you can see in 
figure 11.1. We can improve this graph easily by adding lines connecting the dots as shown 
in figure 11.2. 


Simple Plot - Version 2 lolx] 


Figure 11.2 Adding lines to a 
simple graph 





simpleplot2.py 


scaled = [] 
for x,y in [(12, 56), (20, 94), (33, 98), (45, 120), (61, 180), 
(75, 160), (98, 223)]: 
scaled.append(100 + 3*x, 250 - (4*y)/5) 


canvas.create_line(scaled, fill='royalblue') O 
for x,y in scaled: 
canvas.create_oval (x-6,y-6,x+6,y+6, width=1, 
outline='black', fill='SkyBlue2') 





Code comments 


@ So that we do not have to iterate through the data in a simple loop, we construct a list of x-y 
coordinates which may be used to construct the line (a list of coordinates may be input to the 
create_line method). 


@ We draw the line first. Remember that items drawn on a canvas are layered so we want the 
lines to appear under the blobs. 


© Followed by the blobs. 


Here come the Ginsu knives! We can add line smoothing at no extra charge! If we turn 
on smoothing we get cubic splines for free; this is illustrated in figure 11.3. 
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Simple Plot - Version 3 - Smoothed | — [Oo x| 


250.0 
200.0 
150.0 © 
100.0 


50.0 


10 20 30 40 50 60 70 80 90 100 


Figure 11.3 Smoothing 
the line 





simpleplot3.py 


canvas.create_line(scaled, fill='black', smooth=1) 


I don’t think that needs an explanation! 


11.2. A graph widget 


The previous examples illustrate that it is quite easy to produce simple graphs with a small 
amount of code. However, when it is necessary to display several graphs on the same axes, it is 
cumbersome to produce code that will be flexible enough to handle all situations. Some time 
ago Konrad Hinsen made an effective graph widget available to the Python community. The 
widget was intended to be used with NumPy.* With his permission, I have adapted it to make 
it usable with the standard Python distribution and I have extended it to support additional 
display formats. An example of the output is shown in figure 11.4. In the following code list- 
ing, I have removed some repetitive code. You will find the complete source code online. 


plot.py 


from Tkinter import * 

from Canvas import Line, CanvasText 
import string, math 

from utils import * 

from math import pi 





* NumPy is Numeric Python, a specialized collection of additional modules to facilitate numeric com- 
putation where performance is needed. 
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Figure 11.4 Simple graph 
widget: lines only 





class GraphPoints: 
def __init__ (self, points, attr): 
self.points = points 
self.scaled = self.points 
self.attributes = {} 
for name, value in self._attributes.items(): 
try: 


value = attr[name] 
except KeyError: pass 
self.attributes[name] = value 


def boundingBox (self): 
return minBound(self.points), maxBound(self.points) 
def fitToScale(self, scale=(1,1), shift=(0,0)): 
self.scaled = [] 


for x,y in self.points: 
self.scaled.append((scale[0]*x)+shift[0],\ 
(scale[1]*y)+shift[1]) 


class GraphLine(GraphPoints) : 
def __init__(self, points, **attr): 
GraphPoints.__init__ (self, points, attr) 


attributes = {'color': '‘black', 
'width': diz 


‘smooth': 0, (O 


'splinesteps': 12} 


def draw(self, canvas): 
color = self.attributes['color'] 
width = self.attributes['width'] 
smooth = self.attributes['smooth'] 
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steps = self.attributes['splinesteps'] ‘*@ 
arguments = (canvas, ) o 


if smooth: 
for i in range(len(self.points)): 
xl, yl = self.scaled[i] 
arguments = arguments + (x1, y1) 
else: |O 
for i in range(len(self.points)-1): 
xl, yl = self.scaled[i] 
x2, y2 = self.scaled[i+1] 
arguments = arguments + (xl, yl, x2, y2) 


apply(Line, arguments, {'fill': color, ‘'width': width, 
‘smooth': smooth, (9 
'splinesteps': steps}) 





class GraphSymbols(GraphPoints) : © 
def _ init_ (self, points, **attr): 
GraphPoints.__init_ (self, points, attr) 


_attributes = {'color': 'black', 
'width': 1, 
'fillcolor': 'black', 
"size": 2, 
'fillstyle': '', 
'outline': 'black', 
'marker': 'circle'} 


def draw(self, canvas): 

color = self.attributes['color'] 

size = self.attributes['size'] 

fillcolor = self.attributes['fillcolor'] 

marker = self.attributes['marker'] 

fillstyle = self.attributes['fillstyle'] 

self._drawmarkers(canvas, self.scaled, marker, color, | 9 
fillstyle, fillcolor, size) 


def _drawmarkers(self, c, coords, marker='circle', 


color='black', fillstyle='', fillcolor='',size=2): 
1 = [] 
f = eval('self._' +marker) 
for xc, yc in coords: 
id = f(c, xc, yc, outline=color, size=size, 
fill=fillcolor, fillstyle=fillstyle) _® 


if type(id) is type(()): 
for item in id: 1.append(item) 


else: 
1.append (id) 
return 1 
def _circle(self, c, xc, yc, size=1, fill='', | 


outline='black', fillstyle=''): 
id = c.create_oval(xc-0.5, yc-0.5, xc+0.5, yc+0.5, 
fill=fill, outline=outline, 
stipple=fillstyle) 
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© O 


c.scale(id, xc, yc, size*5, size*5) © 
return id 


# --- Code Removed -~-~----------- 9959255 n nnn nnn nnn nnn nnn nnn nanan n- 





Code comments 


The GraphPoints class defines the points and attributes of a single plot. As you will see later, 
the attributes that are processed by the constructor vary with the type of line style. Note that 
the self._attributes definitions are a requirement for subclasses. 


boundingBox returns the top-left and bottom-right coordinates by scanning the coordinates 
in the points data. The convenience functions are in utils.py. 


£itToScale modifies the coordinates so that they fit within the scale determined for all of 
the lines in the graph. 
def fitToScale(self, scale=(1,1), shift=(0,0)): 
self.scaled = [] 
for x,y in self.points: 
self.scaled.append((scale[0]*x)+shift[0],\ 
(scale[1]*y)+shift [1] ) 
Note that we supply tuples for scale and shift. The first value is for x and the second 

is for y. 
The GraphLine class defines methods to draw lines from the available coordinates. 
The draw method first extracts the appropriate arguments from the attributes dictionary. 


Depending on whether we are doing smoothing, we supply start-end-coordinates for line seg- 
ments (unsmoothed) or a sequence of coordinates (smoothed). 
We then apply the arguments and the keywords to the canvas Line method. Remember that 
the format of the Line arguments is really: 

Line(*args, **keywords) 
GraphSymbols is similar to GraphLine, but it outputs a variety of filled shapes for each of 
the x-y coordinates. 


The draw method calls the appropriate marker routine through the generic __drawmarkers 
method: 
self._drawmarkers(canvas, self.scaled, marker, color, 
fillstyle, fillcolor, size) 
_drawmarkers evaluates the selected marker method, and then it builds a list of the symbols 
that are created. 


£ = eval('self._' +marker) 
for xc, yc in coords: 
id = £(c, xc, yc, outline=color, size=size, 
fill=fillcolor, fillstyle=fillstyle) 
I have included just one of the shapes that can be drawn by the graph widget. The full set are 
in the source code available online. 
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plot.py (continued) 


def _dot(self, c, xc, yc, ... ): 

def _square(self, c, xc, yc, ... ): 

def _triangle(self, c, xc, yc, ... ): 

def _triangle_down(self, c, xc, yc, ... ): 
def. cross'(self,.:c; “xc; “yoy ccs jg 

def _plus(self, c, xc, yc, ... ): 


# --- Code Removed ---~--------------- 7-5-5555 5 555555 n nnn nanan 


class GraphObjects: 
def __init__ (self, objects): 
self.objects = objects 


def boundingBox(self): 
cl, c2 = self.objects[0] .boundingBox () LQ 
for object in self.objects[1:]: 
clo, c2o = object.boundingBox () 
cl = minBound([cl, clo]) 
c2 = maxBound([c2, c2o0]) 
return cl, c2 


def fitToScale(self, scale=(1,1), shift=(0,0)): O 
for object in self.objects: 
object.fitToScale (scale, shift) 


def draw(self, canvas): O 
for object in self.objects: 
object .draw (canvas) 





class GraphBase (Frame): 
def _init_ (self, master, width, height, 
background='white', **kw): 
apply(Frame.__init__, (self, master), kw) 
self.canvas = Canvas(self, width=width, height=height, 
background=background) 
self.canvas.pack(fill=BOTH, expand=YES) 





border_w = self.canvas.winfo_reqwidth() - \ 
string.atoi(self.canvas.cget('width') ) © 
border_h = self.canvas.winfo_reqheight() - \ 
string.atoi(self.canvas.cget('height') ) 
self.border = (border_w, border_h) 
self.canvas.bind('<Configure>'!, self.configure) O 
self.plotarea_size = [None, None] 


self._setsize() 
self.last_drawn = None 





self.font = ('Verdana', 10) 


def configure (self, event): 
new_width = event.width-self.border[0] 
new_height = event.height-self.border[1] 
width = string.atoi(self.canvas.cget('width') ) 
height = string.atoi(self.canvas.cget('height') ) 
if new_width == width and new_height == height: 
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return 
self.canvas.configure(width=new_width, height=new_height) 
self._setsize() 


self.clear() 
self.replot() 


def bind(self, *args): 


def 


apply(self.canvas.bind, args) 


_setsize(self): 
self.width = string.atoi(self.canvas.cget('width' ) ) 
self.height = string.atoi(self.canvas.cget('height') ) 
self.plotarea_size[0] = 0.97 * self.width 
self.plotarea_size[1] = 0.97 * -self.height 


xo = 0.5*(self.width-self.plotarea_size[0]) 
yo = self.height-0.5*(self.height+self.plotarea_size[1]) 
self.plotarea_origin = (xo, yo) 


def draw(self, graphics, xaxis = None, yaxis = None): 


self.last_drawn = (graphics, xaxis, yaxis) 

pl, p2 = graphics. boundingBox() 

xaxis = self._axisInterval(xaxis, p1[0], p2[0]) 
yaxis = self._axisInterval(yaxis, p1[1], p2[1]) 
text_width = [0., 0.] 

text_height = [0., 0.] 


if xaxis is not None: 
pl = xaxis[0], pl1[1] 
p2 = xaxis[1], p2[1] 
xticks = self._ticks(xaxis[0], xaxis[1]) 
bb = self._textBoundingBox(xticks[0][1]) 
text_height[1] = bb[3]-bb[1] 
text_width[0] = 0.5*(bb[2]-bb[0]) 
bb = self._textBoundingBox(xticks[-1][1]) 
text_width[1] = 0.5*(bb[2]-bb[0]) 
else: 
xticks = None 
if yaxis is not None: 
pl = p1[0], yaxis[0] 
p2 = p2[0], yaxis[1] 
yticks = self._ticks(yaxis[0], yaxis[1]) 
for y in yticks: 
bb = self._textBoundingBox(y[1]) 
w = bb[2]-bb[0] 
text_width[0] = max(text_width[0], w) 
h = 0.5* (bb[3]-bb[1]) 
text_height[0] = h 
text_height[1] = max(text_height[1], h) 
else: 
yticks = None 
textl = [text_width[0], -text_height[1]] 


text2 = [text_width[1], -text_height[0]] 
scale ((self.plotarea_size[0]-text1[0]-text2[0]) / \ 


(p2[0]-p1[0]), 
(self.plotarea_size[1]-text1[1]-text2[1]) / \ 
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(p2[1]-p1[1])) 


shift = ((-p1[0]*scale[0]) + self.plotarea_origin[0] + \ 
text1[0], 
(-p1[1]*scale[1]) + self.plotarea_origin[1] + \ 
text1[1]) 


self._drawAxes(self.canvas, xaxis, yaxis, pl, p2, 
scale, shift, xticks, yticks) 

graphics.fitToScale(scale, shift) 

graphics.draw(self.canvas) 


# =~ Codes Removed. S5 SH Sasa Sea Soe Se Se Se Se Se Se oe 





Code comments (continued) 

@ _ The GraphObjects class defines the collection of graph symbologies for each graph. In partic- 
ular, it is responsible for determining the common bounding box for all of the lines. 

@® fitToscale scales each of the lines to the calculated bounding box. 

@ Finally, the draw method renders each of the graphs in the composite. 

@ GraphBase is the base widget class which contains each of the composites. As you will see 
later, you may combine different arrangements of graph widgets to produce the desired effect. 


@ An important feature of this widget is that it redraws whenever the parent container is resized. 
This allows the user to shrink and grow the display at will. We bind a configure event to 
the configure callback. 


plot.py (continued) 


self.canvas.bind('<Configure>', self.configure) 
if _ name_ == '_main_': 
root = Tk() 
@i-s 5. *pis 5, 
data [] 


I 


for i in range(18): 
data.append((float(i)*di, 
(math.sin(float (i) *di)-math.cos(float(i)*di)))) 
line GraphLine(data, color='gray', smooth=0) 
linea = GraphLine(data, color='blue', smooth=1, splinesteps=500) 





graphObject = GraphObjects([line, linea] ) 


© 


graph = GraphBase(root, 500, 400, relief=SUNKEN, border=2) 
graph.pack(side=TOP, fill=BOTH, expand=YES) 


graph.draw(graphObject, '‘automatic', 'automatic') 

Button(root, text='Clear', command=graph.clear) .pack(side=LEFT) 
Button(root, text='Redraw', command=graph.replot) .pack(side=LEFT) 
Button(root, text='Quit', command=root.quit) .pack (side=RIGHT) 


root.mainloop() 
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Code comments (continued) 


@ Using the graph widget is quite easy. First, we create the line/curve that we wish to plot: 


for i in range(18): 
data.append( (float (i) *di, 
(math.sin(float(i)*di)-math.cos(float(i)*di)))) 
line = GraphLine(data, color='gray', smooth=0) 
linea = GraphLine(data, color='blue', smooth=1, splinesteps=500) 





@® Next we create the GraphObject which does the necessary scaling: 
graphObject = GraphObjects([line, linea] ) 
@ Finally, we create the graph widget and associate the Graphobject with it: 








graph = GraphBase(root, 500, 400, relief=SUNKEN, border=2) 
graph.pack(side=TOP, fill=BOTH, expand=YES) 
graph.draw(graphObject, ‘automatic', '‘automatic') 


11.2.1 Adding bargraphs 


Having developed the basic graph widget, it is easy to add new types of visuals. Bargraphs, 
sometimes called /istograms, are a common way of presenting data, particularly when it is 
intended to portray the magnitude of the data, since the bars have actual volume as opposed 
to perceived volume under-the-curve. Figure 11.5 shows some typical bargraphs, in some 
cases combined with line graphs. Note that it is quite easy to set up multiple instances of the 
graph widget. 








Graph Widget - Bar Graph 








Figure 11.5 Adding bar 


JI ] | =e i graphs to the graph 


tml «|| widget 





plot2.py 


from Tkinter import * 
from Canvas import Line, CanvasText, Rectangle 
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class GraphPoints: 
kare Code Removed serenos n ar nnna a a e a ee seen ese 


def fitToScale(self, scale=(1,1), shift=(0,0)): 
self.scaled = [] 
for x,y in self.points: 
self.scaled.append((scale[0]*x)+shift[0],\ 
(scale[1]*y)+shift[1]) 
self.anchor = scale[1]*self.attributes.get('anchor', 0.0)\ o 
+ shift[1] 


# --- Code Removed --~-~----------- 9595555555 nn nnn nn nnn nn nnn nnn nanan nnn 


class GraphBars(GraphPoints) : 
def __init__ (self, points, **attr): 
GraphPoints. init__(self, points, attr) 


_attributes = {'color': 'black', 
'width': 1, 
'fillcolor': 'yellow', 
'size': 3, 
'fillstyle': '', 
‘outline': 'black'} 


def draw(self, canvas): 


color = self.attributes['color'] 

width = self.attributes['width'] 
fillstyle = self.attributes['fillstyle'] 
outline = self.attributes['outline'] 
spread = self.attributes['size'] 
arguments = (canvas, ) 

pl, p2 = self.boundingBox() 


for i in range(len(self.points)): 
xl, yl = self.scaled[il] 
canvas.create_rectangle(xl-spread, yl, x1l+spread, 
self.anchor, fill=color, 
width=width, outline=outline, 
stipple=fillstyle) 


# --- Code Removed -~-~---------- 559555555 n nnn nnn nnn nnn nnn nnn nnn nanan n, 
if _ name == '_main_': 
root = Tk 


() 
root.title('Graph Widget - Bar Graph') 


di = 5.*pi/40. 
data = [] 
for i in range(40): 
data.append((float(i)*di, 
(math.sin(float (i) *di)-math.cos(float(i)*di)))) 


linel = GraphLine(data, color='black', width=2, 
smooth=1) 
linela = GraphBars(data[1:], color='blue', fillstyle='gray25', O 


anchor=0.0) 


line2 = GraphBars([(0,0), (1,145), (2,151), (3,147), (4,22), (5,31), 
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(6,77), (7,125), (8,220), (9,550), (10,560), (11,0) ], 
color='green', size=10) 


151), (3,147), (4,22), (5,31), 
9,550), (10,560), (11,0)], 


line3 = GraphBars([(0,0), (1,145), (2 
(6,77), (7,125), (8,220) 
color='blue', size=10) 

line3a = GraphLine([(1,145), (2,151), (3,147), (4,22), (5,31), 
(6,77), (7,125), (8,220), (9,550), (10,560) ], 
color='black', width=1, smooth=0) 


line4 = GraphBars([(0,0), (1,145), (2,151), (3,147), (4,22), (5,31), 
(6,77), (7,125), (8,220), (9,550), (10,560), (11,0)], 

color='blue', size=10) 

line4a = GraphLine([(1,145), (2,151), (3,147), (4,22), (5,31), 

(6,77), (7,125), (8,220), (9,550), (10,560)], 

color='black', width=2, smooth=1) 

















[linela, linel1]) 
[line2]) 

{line3a, line3]) 
[line4, line4a]) 


graphObject = GraphObjects ( 
graphObject2 = GraphObjects ( 
graphObject3 = GraphObjects ( 
graphObject4 = GraphObjects ( 
f1 = Frame (root) 
f2 = Frame (root) 








graph = GraphBase(f1, 500, 350, relief=SUNKEN, border=2) 
graph.pack(side=LEFT, fi11=BOTH, expand=YES) 
graph.draw(graphObject, ‘automatic', 'automatic') 


graph2= GraphBase(fl, 500, 350, relief=SUNKEN, border=2) 
graph2.pack(side=LEFT, fi11=BOTH, expand=YES) 
graph2.draw(graphObject2, 'automatic', '‘automatic') 





graph3= GraphBase(f2, 500, 350, relief=SUNKEN, border=2) 
graph3.pack(side=LEFT, fil1=BOTH, expand=YES) 
graph3.draw(graphObject3, '‘automatic', '‘automatic') 





graph4= GraphBase(f2, 500, 350, relief=SUNKEN, border=2) 
graph4.pack(side=LEFT, fil1=BOTH, expand=YES) 
graph4.draw(graphObject4, 'automatic', '‘automatic') 











£1.pack ( 


) 
£2.pack() 


Peme Code Removed: =-aS= SPSS PS ee te sete Set SSS tes ee Se ee ee ee 





Code comments 


@ There's not much to explain here; I think that the changes are fairly self-explanatory. How- 
ever, anchor is worthy of a brief note. In the case of the sine/cosine curve, we want the bars 
to start on zero. This is the anchor value. If we don’t set it, we'll draw from the x-axis regard- 
less of its value. 


self.anchor = scale[1]*self.attributes.get('anchor', 0.0) + shift[1] 


© The bargraph has some slightly different options that need to be set. 
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© The bargraph simply draws a rectangle for the visual. 


© Defining the data is similar to the method for lines. Note that I have omitted the first data 


11.2.2 





point so that it does not overlay the y-axis: 


linela = GraphBars(data[1:], color='blue', fillstyle='gray25', 
anchor=0.0) 


Pie charts 


As Emeril Lagasse* would say, “Let’s kick it up a notch!” Bargraphs were easy to add, and add- 
ing pie charts is not much harder. Pie charts seem to have found a niche in management 
reports, since they convey certain types of information very well. As you will see in 
figure 11.6, I have added some small details to add a little extra punch. The first is to scale the 
pie chart if it is drawn in combination with another graph—this prevents the pie chart from 
getting in the way of the axes (I do not recommend trying to combine pie charts and bar 
graphs, however). Secondly, if the height and width of the pie chart are unequal, I add a little 
decoration to give a three-dimensional effect. 

There is a problem with Tk release 8.0/8.1. A stipple is ignored for arc items, if present, 
when running under Windows; the figure was captured under UNIX. Here are the changes to 
create pie charts: 


Figure 11.6 Adding pie charts to the 
graph widget 





* Emeril Lagasse is a popular chef/proprietor of restaurants in New Orleans and Las Vegas in the USA. 
He is the exhuberant host of a regular cable-television cooking show. The audience join Emeril loudly 
in shouting “Bam! Let’s kick it up a notch!” as he adds his own Essence to his creations. 
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plot3.py 


# --- Code Removed -------~-------------------------- 


class GraphPie(GraphPoints) : 
def _ init__(self, points, **attr): 
GraphPoints. init__(self, points, attr) 


attributes = {'color': 'black', 
'width': 1, 
'fillcolor': 'yellow', 
"size': 2, 
'fillstyle': '', 
‘outline': 'black'} 


def draw(self, canvas, multi): 


width = self.attributes['width'] 

fillstyle = self.attributes['fillstyle'] 

outline = self.attributes['outline'] 

colors = Pmw.Color.spectrum(len(self.scaled) ) @ 
arguments = (canvas, ) 

x1 = string.atoi(canvas.cget('width' )) 

yl1 = string.atoi(canvas.cget('height') ) 

adj = 0 


if multi: adj = 15 
xy = 25+adj, 25+adj, x1-25-adj, y1-25-adj 


xys = 25+adj, 25+adj+10, x1-25-adj, y1-25-adj+10 


tt = 0.0 

i= 0 

for point in self.points: 
tt = tt + point[1] 

start = 0.0 

if not x1 == yl: 


canvas.create_arc(xys, start=0.0, extent=359.99, 
£i11='gray60', outline=outline, 


style='pieslice' ) 


for point in self.points: 
xl, yl = point 
extent (y1/tt)*360.0 


canvas.create_arc (xy, start=start, extent=extent, 


fill=colors[i], width=width, 


outline=outline, stipple=fillstyle, 


style='pieslice' ) 
start = start + extent 
i = i+1 


class GraphObjects: 
def __init__(self, objects): 


self.objects = objects 
self.multiple = len(objects)-1 
# >> Code Retioved! s-sso-ss Se See Sea 
290 CHAPTER 11 


GRAPHS AND CHARTS 








def draw(self, canvas): 
for object in self.objects: 
object.draw(canvas, self.multiple) O 


Paer code Removed eee aaa E a a e a a 


if a == ' | main__': 
root = ) 
(' 


k ( 
root.title('Graph Widget - Piechart' 


piel = GraphPie([(0,21), (1,77), (2,129), (3,169), (4,260), (5,377), 
(6,695), (7,434) ]) 





pie2 = GraphPie([(0,5), (1,22), (2,8), (3,45), (4,22), 
(5,9), (6,40), (7,2), (8,56), (9,34), 
(10,51), (11,43), (12,12), (13,65), (14,22), 
(15,15), (16,48), (17,16), (18,45), (19,19), 
(20,33)], fillstyle='gray50', width=2) 

pie3 = GraphPie([(0,5), (1,22), (2,8), (3,45), (4,22), 
(5,9), (6,40), (7,2), (8,56), (9,34), 
(10, 5y Gi; 43), (12,12), (13,65), (14,22), 
(15,15), (16,48), (17,1 16), (18,45), (19,19), 
(20,33)]) 


pieline4 = GraphLine([(0,21), (1,77), (2,129), (3,169), (4,260), 
(5,377), (6,695) ,(7,434)], width=3) 
pielines4 = GraphSymbols([(0,21), (1,77), (2,129), (3,169), (4,260), 
(5,377), (6,695), (7,434) ], 
marker='square', fillcolor='yellow') 


graphObject1 = GraphObjects([piel]) 

graphObject2 = GraphObjects([pie2]) 

graphObject3 = GraphObjects([pie3]) 
([ 


graphObject4 = GraphObjects([piel, pieline4, pielines4]) 


f1 = Frame(root) 
f2 = Frame (root) 


graphl= GraphBase(f1, 300, 300, relief=SUNKEN, border=2) 
graphl.pack(side=LEFT, fill=BOTH, expand=YES) 
graph1.draw (graphO0bject1) 





#7; (Code ‘Removed. --=-SaSsssSs SSeS See SSeS Sas a a a ee 





Code comments 
The pie chart implementation assigns a spectrum of colors to the slices of the pie, one color 
value per slice. This gives a reasonable appearance for a small number of slices. 

colors = Pmw.Color.spectrum(len(self.scaled) ) 
This code adjusts the position of the pie chart for cases where we are displaying the pie chart 
along with other graphs: 

adj = 0 

if multi: adj = 15 
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xy = 25+adj, 25+adj, x1-25-adj, y1-25-adj 
xys = 25+adj, 25+adj+10, x1-25-adj, y1-25-adj+10 


The shadow disc (xys) is used if the pie chart is being displayed as a tilted disc. 


© The shadow is drawn as a pie slice with an almost complete circular slice: 
if not x1 == y1: 
canvas.create_arc(xys, start=0.0, extent=359.99, 
fill='gray60', outline=outline, style='pieslice') 
© Asin the case of adding bar graphs, adding pie charts requires a specialized draw routine. 
@ The scaling factors are determined by the presence of multiple graphs in the same widget. 


@  self.multiple is passed down to the graph object’s draw method. 


As you have seen in these examples, adding a new graph type is quite easy and it produces 
some reasonably attractive graphs. I hope that you can make use of them and perhaps create 
new visual formats for the Python community. 


11.3. 3-D graphs 


If you have a large amount of data and that data follows a pattern that encourages examining 
the graphs on the same axes (same scale), there are a number of ways to display the graphs. 
One way is to produce a series of separate graphs and then present them side by side. This is 
good if you want to examine the individual graphs in detail, but it does not readily demon- 
strate the relationship between the graphs. To show the relationship you can produce a single 
diagram with all of the plots superimposed using different symbols, line styles, or combina- 
tions of both. However, there is often a tendency for the lines to become entangled or for 
symbols to be drawn on top of each other. This can produce very confusing results. 

I always like to solve these problems by producing three-dimensional graphs. They allow 
the viewer to get a sense of the topology of the data as a whole, often highlighting features in 
the data that may be difficult to discern in other formats. The next example illustrates such a 
graph (see figure 11.7). I have taken a few shortcuts to reduce the overall amount of code. For 
example, I have made no provision for modifying the orientation of the axes or the viewing 
position. PII leave that as an exercise for the enthusiastic reader! 


3dgraph.py 


from Tkinter import * 
import Pmw, AppShell, math 


class Graph3D (AppShell.AppShell): 
usecommandarea = 1 


appname = '3-Dimensional Graph' 
frameWidth = 800 
frameHeight = 650 


def createButtons (self): 
self.buttonAdd('Print', 
helpMessage='Print current graph (PostScript)', 
statusMessage='Print graph as PostScript file', 
command=self.iprint) 
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Figure 11.7 three-dimensional graphical display 


self. 


buttonAdd('Close', 
helpMessage='Close Screen', 
statusMessage='Exit', 
command=self.close) 





def createBase(self): 


self. 
self. 
self. 


self 


self. 
self. 
self 
self. 
self. 
self. 
self. 
self 
self. 
self. 
self 


self. 


3-D GRAPHS 


width = self.root.winfo_width()-10 

height = self.root.winfo_height ()-95 

canvas = self.createcomponent('canvas', (), None, 
Canvas, (self.interior(),), width=self.width, 


height=self.height, background="black") 


.canvas.pack(side=TOP, expand=YES, f£i11=BOTH) 


awidth = int(self.width * 0.68) 
aheight = int(self.height * 0.3) 


-hoffset = self.awidth / 3 


voffset = self.aheight +3 
vheight = self.voffset / 2 


hrowoff = (self.hoffset / self.rows) 

vrowoff = self.voffset / self.rows 

.xincr = float(self.awidth) / float(self.steps) 

xorigin = self.width/3.7 

yorigin = self.height/3 

-yfactor = float(self.vheight) / float(self.maxY-self.miny) 
canvas.create_polygon(self.xorigin, self.yorigin, 
self.xorigin+self.awidth, self.yorigin, 9 
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self.xorigint+self.awidth-self.hoffset, self.yorigin+self.voff- 
set, 
self.xorigin-self.hoffset, 


self.xorigin, self.yorigin, 


self.yorigintself.voffset, 
fill='', outline=self.lineColor) 


self.canvas.create_rectangle(self.xorigin, 
self.xorigin+self.awidth, 
fill='', 


self.yorigin-self.vheight, 
self.yorigin, 
outline=self.lineColor) 


self.canvas.create_polygon(self.xorigin, self.yorigin, 


self.xorigin-self.hoffset, self.yorigin+self.voffset, 
self.xorigin-self.hoffset, self.yorigin+self.voffset-self.vheight, 
self.xorigin, self.yorigin-self.vheight, 





fill='', outline=self.lineColor) 


-ho 


% 


self.canvas.create_text (self.xorigin-self 
self.yorigin+self.voffset, text='%d' 
fill=self.lineColor, anchor=E) 

canvas.create_text (self.xorigin-self.ho 
self.yorigin+self.voffset-self.vheight, 
self.maxY, fill=self.lineColor, anchor= 





self. 


self.canvas.create_text (self.xorigin-self.ho 
self.yorigin+self.voffset+5, text='%d' 
fill=self.lineColor, anchor=N) 
self.canvas.create_text (self.xorigint+self.aw 
self.yorigin+self.voffset+5, text='%d' 


fill=self.lineColor, anchor=N) 





def initData(self): 
self. 
self. 
self. 
self. 
self. 
self. 
self. 


0 
100 
0 
100 
100 
10 


minY 
maxY 


minX = 
maxX = 
steps 
rows 


spectrum 


intensity=0.8, 
'gray80' 
30 
70 


self. 
self. 
self. 


lineColor = 
lowThresh = 
highThresh 


def transform(self, 
rgb 
retval = 
for v in 


base, factor): 
self.winfo_rgb (base) 
nn 
[rgb[0], rgb[1], 
(v* factor) /256 
if v > 255: 255 
if v < 0: v 0 
retval = "%s%02x" 
return retval 


rgb[2]]: 
y= 


Vv 


% (retval, v) 


def plotData (self, row, rowdata): 


rootx = self.xorigin - (row*self.hrowoff) 
rooty = self.yorigin + (row*self.vrowoff) 
cidx = 0 


294 CHAPTER 11 


Pmw.Color.spectrum(self.steps, 


ffset-5, 
self.miny, 


ffset-5, 
text='%d' % \ 
E) 





ffset, 

% self.minx, 
idth-self.hoffset, 
% self.maxX, 


© 


saturation=0.8, 


extraOrange=1) 
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lasthv = self.maxY*self.yfactor 
xadj = float(self.xincr) /4.0 
lowv = self.lowThresh*self.yfactor 
for datum in rowdata: 
lside = datum*self.yfactor 
color = self.spectrum[cidx] 
if datum <= self.lowThresh: 
color = self.transform(color, 0.8) 
elif datum >= self.highThresh: 
color = self.transform(color, 1.2) 


self.canvas.create_polygon(rootx, rooty, rootx, 
rootx-self.hrowoff, rooty-lsidet+tself.vrowoff, 
rootx-self.hrowoff, rooty+self.vrowoff, 
rootx, rooty, fill=color, outline=color, 


width=self.xincr) 
base = min(min(lside, lasthv), lowv) 


rooty-lside, 


self.canvas.create_line(rootx-xadj, rooty-lside, 
rootx-xadj-self.hrowoff, rooty-lsidet+self.vrowoff, 
rootx-xadj-self.hrowoff, rooty+self.vrowoff-base, 


fill='black', width=1) 
lasthv = lowv = lside 


cidx = cidx + 1 
rootx = rootx + self.xincr 


def makeData(self, number, min, max): 
import random 
data = [] 
for i in range(number) : 
data.append(random.choice(range(min, max) ) ) 
return data 


def demo(self): 
for i in range(self.rows): 
data = self.makeData(100, 4, 99) 
self.plotData(i, data) 
self.root.update() 


def close(self): 
self.quit() 


def createInterface(self): 
AppShell.AppShell.createInterface(self) 
self.createButtons () 
self.initData() 
self.createBase() 


_ name_ == '_ main_': 

graph = Graph3D() 
graph.root.after(100, graph.demo) 
graph.run() 
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Code comments 
Despite the complex diagram, the code is quite simple. Much of the code is responsible for 
drawing the frame and text labels. 
You may have seen the transform method used in “Adding a hex nut to our class library” on 
page 131. Its purpose is to calculate a lighter or darker color intensity when given a color. 

def transform(self, base, factor): 
The transformed color is used to highlight values which exceed a high threshold and to deac- 
centuate those below a lower threshold. 


For this example, we generate ten rows of random data. 
Because the data was generated randomly, the effect is quite busy. If data is supplied from 


topological sources, the plot may be used to provide a surface view. Figure 11.8 illustrates the 
kind of three-dimensional plot that can be produced with such data. 


Enea 


File 








Print Close 


r 








Figure 11.8 Using the 3-D to present topological data 


Strip charts 


In this final section we are going to look briefly at using strip charts to display data coming from 
a source of continuously changing data. Such displays will typically build a plot incrementally as 
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the data is made available or polled at some time interval, and then they reset the chart when the 
maximum space has been filled. 

Strip charts are an ideal medium for displaying performance data; data from sensors, such 
as temperature, speed, or humidity; data from more abstract measurements (such as the average 
number of items purchased per hour by each customer in a grocery store); and other types of 
data. They also can be used as a means of setting thresholds and triggering alarms when those 
thresholds have been reached. 

The final example implements a weather monitoring system utilizing METAR* data. 
This encoded data may be obtained via FTP from the National Weather Service in the United 
States and from similar authorities around the globe. We are not going to enter a long tutorial 
about how to decode METARs, since that would require a chapter of its own. For this example, 
I am not even going to present the source code (there is really too much to use the space on 
the printed page). The source code is available online and it may be examined to determine 
how a simple FTP poll may be made to gather data continuously. 

Take a look at figure 11.9 which shows the results of collecting the data from Tampa Bay, 
Florida (station KTPA), for about nine hours, starting at about 8:00 am. EST. The graphs 
depict temperature, humidity, altimeter (atmospheric pressure), visibility, wind speed, wind 
direction, clouds over 10,000 feet and clouds under 25,000 feet. 


‘Weather Monitor (KTPA) 





Refresh Rate: [5 Minutes IM Display: [12 Hours XY Station: |KTPA Tampa x Set Thresholds 





Figure 11.9 Strip chart display with polled meteorological data 





If you are a weather buff or a private pilot, you will be familiar with the automated, encoded weather 
observations that are posted at many reporting stations, including major airports, around the world. 
Updated on an hourly basis (more frequently if there are rapid changes in conditions), they contain 
details of wind direction and speed, temperature, dewpoints, atmospheric pressure, cloud cover and 
other data important to aviation in particular. 
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The presentation for the strip chart is intended to be similar to an oscilloscope or some 
other piece of equipment. Normally reverse-video is not the best medium for presenting data; 
this may be one of the exceptions. 

The example code implements a threshold setting which allows the user to set values 
which trigger an alarm or warning when values are above or below the selected threshold. Take 
a look at figure 11.10 which shows how thresholds can be set on the data. This data comes from 
my home airport (Providence, in Warwick, Rhode Island) and it shows data just before a thun- 
derstorm started. 


CEN (= lolx) 
Eile Help | 











Temp|75 w| F [warn over w] 
Altimeter [29.0 _¥| In. Hg [Alarm Under w] 
Wind Speed [20 =| MPH [warnover | 
Humidity [90 w|  %ə [Warn over i] 
Ceiling [5000 x| Feet |Alarm Under x| 








Apply Cancel 








Figure 11.10 Setting thresholds 
on data values 





If you look at figure 11.11 you can observe how the cloud base suddenly dropped below 
5000 feet and triggered the threshold alarm. 

If you do use this example please do not set the update frequency to a high rate. The data 
on the National Oceanic and Atmospheric Administration (NOAA) website is important for 
many pilots—leave the bandwidth for them! 


Summary 


Drawing graphs may not be necessary for many applications, but the ability to generate attrac- 
tive illustrations from various data sources may be useful in some cases. While there are several 
general-purpose plotting systems available to generate graphs from arbitrary data, there is 
something satisfying about creating the code yourself. 
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Figure 11.11 Alarm and warning thresholds 
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navigation” 301 


All successful GUIs provide a consistent and convenient means of navigation between their 
graphical elements. This short chapter covers each of these methods in detail. Some 
advanced navigation methods will be discussed to provide a guide to the topic. From the 
methods presented, you should be able to identify appropriate patterns for your applica- 
tion and apply the methods. 


Introduction: navigation models 


This chapter is all about focus. Specifically, keyboard focus, which is at the widget level and 

determines where keyboard events are delivered. Window focus is strictly a feature of the 

window manager, which is covered in more detail in “The window manager” on page 306. 
There are normally two focus models: 


Pointer When a widget contains the pointer, all keyboard events are directed to the 
widget. 

Explicit The user must click on the widget to tab from widget to widget to set focus 
on a particular widget. 
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12.3 


There are advantages and disadvantages for both models. Many users like the pointer 
model, since a simple movement of the mouse positions the pointer and requires no clicking. 
However, if the mouse is accidentally moved, the keyboard events may be directed to an unin- 
tended widget. The explicit model requires the user to click on every window and widget that 
focus is to be directed to. However, even if the pointer moves out of the widget, keyboard 
events are directed to it. On Win32 and MacOS, explicit focus is the default, whereas on UNIX, 
pointer focus is the default. 

Tk (and therefore Tkinter) implements an explicit model within a given top-level shell, 
regardless of how the window manager is configured. However, within the application, the 
window manager is capable of overriding focus to handle system-level operations, so focus can 
be lost. 


Mouse navigation 


Most computer users are familiar with using the mouse to select actions and objects on the 
screen. However, there are times when stopping keyboard input to move the mouse is incon- 
venient; a touch typist will lose station and have to reestablish it before continuing. Therefore, 
it is usually a good idea to provide a sensible series of tab groups which allow the user to move 
from widget to widget and area to area in the GUI. This is discussed in more detail in the next 
section. 

When the mouse is used to select objects, you need to consider some important human 
factors: 


1 Widget alignment is important. If widgets are arranged aimlessly on the screen, addi- 
tional dexterity is needed to position the mouse. Widgets arranged in rows and columns 
typically allow movement in one or two axes to reposition the pointer. 


2 The clickable components of a widget need to be big enough to ensure that the user does 
not have to reposition the pointer to hit a target. However, this may interfere with the 
GUIs visual effectiveness. 

3 Ensure that there is space between widgets so that the user cannot accidentally choose an 
adjacent widget. 

4 Remember that not all pointing devices are equal. While a mouse can be easy to use to 


direct the pointer to a clickable area, some of the mouse buttons (the little buttons 
embedded in the keyboard on certain laptop computers) can be difficult to control. 


Unless Tkinter (Tk) is directed to obey strict Motif rules, it has a useful property that 
allows it to change the visual attributes of many widgets as the pointer enters the widgets. This 
can provide valuable feedback to the user that a widget has been located. 


Keyboard navigation: 
“mouseless navigation” 
It is easy to forget to provide alternate navigation methods. If you, as the programmer, are 


used to using the mouse to direct focus, you may overlook mouseless navigation. However, 
there are times when the ability to use Tab or Arrow keys to get around a GUI are important. 
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There may be times when the mouse is unavailable (I’ve had problems with a cat sleeping on 
my desk and leaving mouse-jamming hairs!) or when an application is intended to be 
deployed in a hostile environment where a mouse just would not survive. 

This method of navigation does require some discipline in how your GUI is created. The 
order in which focus moves between and within groups is determined by the order in which 
widgets are created. So careless maintenance of a GUI can result in erratic behavior, with focus 
jumping all over the screen. Also, some widgets cannot accept focus (if they are disabled, for 
instance) and others bind the navigation keys internally (the Text widget allows you to enter 
Tab characters, for instance). 

It is also important to remember that the pointer always directs events (such as Enter, 
Leave and Button1) to the widget under it, regardless of where the keyboard focus is set. 
Thus, you may have to change focus to a widget if it does not take keyboard focus itself. 


12.4 Building navigation into an application 


Let’s look at a simple example which allows you to discover how widgets behave in the focus 
models and under certain states. Widgets with the takefocus option set to true are placed 
in the window’s tab group and focus moves from one widget to the next as the TAB key is 
pressed. If the widget’s highlightthickness is at least one pixel, you will see which widget 
currently has focus. One thing to note is that there is somewhat less control of the navigation 
model under Tkinter. This is not normally a problem, but X Window programmers may find 
the restrictions limiting. 


Example_12_1.py 


from Tkinter import * 


class Navigation: 
def __init__(self, master): 


frame = Frame(master, takefocus=1, Eocene ae 
highlightcolor='blue') 

Label(frame, text=' ') .grid(row=0, column=0,sticky=W) 

Label(frame, text=' ') .grid(row=0, column=5,sticky=W) 


self.Bl = self.mkbutton(frame, 'B1', 
self.B2 = self.mkbutton(frame, 'B2', 
self.B3 = self.mkbutton(frame, 'B3', 
self.B4 = self.mkbutton(frame, 'B4', 
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frame2 = Frame(master, takefocus=1, highlightthickness=2, 
highlightcolor='green' ) 





Label (frame2, text=' ') .grid(row=0, column=0,sticky=W) 

Label (frame2, text=' ') .grid(row=0, column=4,sticky=W) 
self.Disable = self.mkbutton(frame2, 'Disable', 1, self.disable) 
self.Enable = self.mkbutton(frame2, 'Enable', 2, self.enable) 
self.Focus = self.mkbutton(frame2, 'Focus', 3, self.focus) 


frame3 = Frame(master, takefocus=1, highlightthickness=2, 
highlightcolor='yellow' ) 

Label (frame3, text=' ') .grid(row=0, column=0,sticky=W) 

Label (frame2, text=' ') .grid(row=0, column=4,sticky=W) 
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self.text = Text(frame3, width=20, height=3, highlightthickness=2) 
self.text.insert (END, 'Tabs are valid here') 
self.text.grid(row=0, col=1, columnspan=3) 





frame.pack(fill=X, expand=1) 
frame2.pack(fill=X, expand=1) 
frame3.pack(fill=xX, expand=1) 


def mkbutton(self, frame, button, column, action=None) : oe 
button = Button(frame, text=button, highlightthickness=2) 
button.grid(padx=10, pady=6, row=0, col=column, sticky=NSEW) 
if action: 
button. config (command=action) 


return button 


def disable(self): 
self.B2.configure(state=DISABLED, background='cadetblue' ) 
self.Focus.configure(state=DISABLED, background='cadetblue' ) 


def enable(self): 
self.B2.configure(state=NORMAL, background=self.B1l.cget ('background' ) ) 
self.Focus.configure(state=NORMAL, 
background=self.Bl.cget ('background' ) ) 


def focus(self): 
self.B3.focus_set() 


root = Tk() 

root.title('Navigation') 

top = Navigation(root) 

quit = Button(root, text='Quit', command=root.destroy) 
quit.pack(side=BOTTOM, pady=5) 


root.mainloop() 





Code comments 


To show where keyboard focus is, we must give the highlight size, since the default for a 
Frame is 0. The color is also set so that it is easy to see. 


The Text widget also requires highlightthickness to be set. Text widgets are in the class 
of widgets that do not propagate Ta characters so you cannot navigate out of a Text widget 
using the Tas key (you must use CTRL-TAB). 


Buttons are window-system dependent. On Win32, buttons show their highlight as a dotted 
line, whereas Motif widgets require you to set the highlight width. If your application is tar- 
geted solely for Win32, you could omit the highlightthickness option. 


Let’s run the code in example 12.1 and see how Tas-key navigation works: 

Each time you press the TAB key, the focus will move to the next widget in the group. 
To reverse the traversal, use the SHIFT-TAB key. In the second frame in figure 12.1, you can see 
that the frame is showing a highlight. Tkinter gets the order of the widgets right if you make 
sure that the widgets are presented to the geometry manager in the order that you want to nav- 
igate. If you do not take care, you will end up with the focus jumping all over the GUI as you 
attempt to navigate. 
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Figure 12.1 Using the Tab key to select a frame 
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Once you have focus, you can activate the widget using the SPACE bar (this is the default 
SELECT key, certainly for Win32 and Motif) or you can click on any widget using the pointer. 
Notice in figure 12.2 that the Enable button shows that it has been traversed to using TAB key, 
but that we select Disable with the pointer. Keyboard focus remains with the Enable button, 
so pressing the SPACE key will re-enable the buttons. 


Navigation Navigation 


Button1 Press 










Disable | 


i are valid here Tabs are valid here 


cut Pa 


Figure 12.2 Demonstrating the difference between keyboard and pointer focus 


Text widgets use TAB keys as separators, so the default binding does not cause traversal 
out of the widget. In figure 12.3 you can see that tabs are inserted into the text. To move out 
of the widget we must use CTRL-TaB which is not bound to the Text widget. 
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Figure 12.3 Using CONTROL-TAB to navigate out of a Text widget 
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12.6 


SUMMARY 


Image maps 


In “Image maps” on page 191, we looked at an implementation of image maps. It used 
pointer clicks to detect regions on the image and to select mapped areas. This technique can- 
not support mouseless operation, so if this is necessary, you have some work to do. 

One solution is to overlay the image with objects that can take focus, then you can tab 
from object to object. This does work (the application shown on page 232 uses this technique 
to place buttons over button images on a ray-traced image), but it does require much more 
planning and code. 


Summary 


This chapter is another illustration of the fact that an application developer should consider 
its end-users carefully. If you are developing an application for a single group of users on uni- 
form hardware platforms, then it may not be necessary to think about providing alternate 
means for navigating the GUIs. However, if you have no control of the end-user’s environ- 
ment you can change their perception of your application greatly by allowing alternate navi- 
gation models. 
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The window manager 


13.1 What is a window manager? 306 13.4 Icon methods 309 
13.2 Geometry methods 307 13.5 Protocol methods 309 
13.3 Visibility methods 308 13.6 Miscellaneous wm methods 310 


Even though it is possible to build applications that have no direct communication with 
the window manager, it is useful to have an understanding of the role that the window 
manager (wm) has in X Window, Win32 and MacOS environments. This chapter covers 
some of the available wm facilities and presents examples of their use. 


13.1 What is a window manager? 


If you already know the answer to that question, you may want to skip ahead. It is per- 
fectly possible to develop complex GUI-based applications without knowing anything 
about the window manager. However, many of the attributes of the displayed GUI are 
determined by the window manager. 

Window managers exist in one form or another for each of the operating systems; 
examples are mwm (Motif), dtwm (CDE) and ovwm (OpenView). In the case of Win32, 
the window manager is just part of the operating system rather than being a separate appli- 
cation. The main functions that window managers typically support are these: 
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1 Management of windows (obviously!): placement, sizing, iconizing and maximizing, for 
example. 


Appearance and behavior of windows and the relationship of windows in an application. 


Management of one or more screens. 


Aà WwW N 


Keyboard focus control. 
5 Window decoration: titles, controls, menus, size and position controls. 
6 Icons and icon management (such as iconboxes and system tray). 
7 Overall keybindings (before application bindings). 
8 Overall mouse bindings. 
9 Root-window menus. 
10 Window stacking and navigation. 
11 Default behavior and client resources (.XDefaults). 
12 Size and position negotiation with windowing primitives (geometry managers). 


13 Device configuration: mouse double-click time, keyboard repeat and movement thresh- 
olds, for example. 


Not all window managers support the same features or behave in the same way. However, 
Tkinter supports a number of window-manager-related facilities which may support your 
application. Naturally, the names of the facilities are oriented to Tk, so you may not recognize 
other manager’s names immediately. 


Geometry methods 


Geometry methods are used to position and size windows and to set resize behavior. It is 
important to note that these are reguests to the window manager to allocate a given amount of 
space or to position the window at a particular screen position. There is no guarantee that the 
window manager will observe the request, since overriding factors may prevent it from hap- 
pening. In general, if you get no apparent effect from geometry methods, you are probably 
requesting something that the window manager cannot grant or you are requesting it at the 
wrong time (either before window realization or too late). 

You normally apply window manager methods to the TopLeve1 widget. 

To control the size and position of a window use geometry, giving a single string as the 
argument in the format: 


widthxheight+xoffset+yoffset 
root.geometry (‘%dx%d+%d+%d’ % (width, height, x, y)) 


Note that it is valid to supply either widthxheight or +xoffset+yoffset as separate 
arguments if you just want to set those parameters. 
Without arguments, self . geometry () returns a string in the format shown above. 
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Ne: In general, you should issue geometry requests at most only once when a 

window is first drawn. It is not good practice to change the position of windows 
under program control; such positioning should be left for the user to decide using the 
window manager controls. 





Setting the minimum and maximum dimensions of a window is often a good idea. If you 
have designed an application which has a complex layout, it may be inappropriate to provide 
the user with the ability to resize the window. In fact, it may be impossible to maintain the 
integrity of a GUI if you do not limit this ability. However, Tkinter GUIs using the Pack or 
Grid geometry managers are much easier to configure than equivalent X window GUIs. 


window.maxsize(width, height) 
window.minsize(width, height) 


window.minsize() and window.maxsize() with no arguments return a tuple 
(width, height). 

You may control the resize capability using the resizable method. The method takes 
two boolean flags; setting either the width or height flags to false inhibits the resizing of 
the corresponding dimension: 


resizable(1, 0) # allow width changes only 
resizable(0, 0) # do not allow resizing in either dimension 


Visibility methods 


Window managers usually provide the ability to iconify windows so that the user can declut- 
ter the workspace. It is often appropriate to change the state of the window under program 
control. For example, if the user requests a window which is currently iconified, we can 
deiconify the window on his behalf. For reasons which will be explained in “Programming 
for performance” on page 348, it is usually better to draw complex GUIs with the window 
hidden; this results in faster window-creation speeds. 

To iconify a window, use the iconify method: 


root.iconify() 
To hide a window, use the withdraw method: 
self.toplevel.withdraw() 


You can find out the current state of a window using the state method. This returns a 
string which is one of the following values: normal (the window is currently realized), iconic 
(the window has been iconified), withdrawn (the window is hidden), or icon (the window 
is an icon). 


state = self.toplevel.state() 
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If a window has been iconified or withdrawn, you may restore the window with the 
deiconify method. It is not an error to deiconify a window that is currently displayed. Make 
sure that the window is placed on top of the window stack by calling 1ift as well. 


self .deiconify() 
self.1lift() 


Icon methods 


The icon methods are really only useful with X Window window managers. You have limited 
control over icons with most window managers. 
To set a two-color icon, use iconbitmap: 


self.top.iconbitmap (myBitmap) 


To give the icon a name other than the window’s title, use iconname: 





self.top.iconname('Example' ) 


You can give the window manager a hint about where you want to position the icon (how- 
ever, the window manager may place the icon in an iconbox if one is defined or wherever else 
it wishes): 


self.root.iconposition(10,200) 


If you want a color bitmap, you must create a Label with an image and then use icon- 
window: 


self.label = Label(self, image=self.img) 
self.root.iconwindow(self.label) 


Protocol methods 


Window managers that conform to the ICCCM* conventions support a number of protocols: 








* WM_DELETE_WINDOW ‘The window is about to be deleted. 
* WM_SAVE_YOURSELF Saves client data. 
* WM_TAKE_FocuS The window has just gained focus. 











You normally will use the first protocol to clean up your application when the user has 
chosen the exit window menu option and destroyed the window without using the applica- 
tion’s Quit button: 


self.root.protocol (WM_DELETE_ WINDOW, self.cleanup) 


























In Python 1.6, the WM_DELETE_WINDOW protocol will be bound to the window’s 
destroy method by default. 








* ICCCM stands for Inter-Client Communication Conventions Manual, which is a manual for client 
communication in the X environment. This pertains to UNIX systems, but Tk emulates the behavior 
on all platforms. 
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WM_SAVE_YOURSELF is less commonly encountered and is usually sent before a 
WM_DELETE_WINDOW is sent. WM_TAKE_FOCUS may be used by an application to allow special 
action to be taken when focus is gained (perhaps a polling cycle is executed more frequently 
when a window has focus, for example). 








Miscellaneous wm methods 


There are several window manager methods, many of which you may never need to look at. 
They are documented in “Inherited methods” on page 433. However, you might find a few of 
them useful. 

To raise or lower a window in the window stack, use 1ift and lower (you cannot use 
“raise” since that is a Python keyword): 


self.top.lift() # Bring to top of stack 
self.top.lift (name) # Lift on top of ‘name’ 
self.top.lower(self.spam) # Lower just below self.spam 


To find which screen your window is on (this is really only useful for X Window), use: 


screen = self.root.screen() 
print screen 
20.1 





Ne Win32 readers The numbers returned refer to the display and screen within 
that display. X window is capable of supporting multiple display devices on the 
same system. 
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PART Pi 


Putting it all together... 


P. 3 covers a number of topics. Not all relate directly to Tkinter, or even Python, necessarily. In 
chapter 14 we begin by looking at building extensions to Python. Extensions can be an effective way 
of adding new functionality to Python or they may be used to boost performance to correct problems 
when youre using native Python. 

Chapter 15 looks at debugging techniques for Python and Tkinter applications, and chapter 16 
examines GUI design. Both of these areas can be problematic to programmers, particularly those who 
are new to GUI applications. 

Chapter 17 looks at techniques to get optimum performance from applications. This area can have 
a dramatic impact on whether your users will like or dislike the interface you have designed. 

In chapter 18 we examine threads and other asynchronous techniques. This is only an introduc- 
tion to the subject, but it may provide a starting point for readers who are interested in this topic. 

Finally, chapter 19 documents some methods to package and distribute Python and Tkinter appli- 
cations. While it’s not exhaustive, it should help programmers to deliver a Python application without 
involving the end user in setting up complex systems. 
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Extending Python 


14.1 Writing a Python extension 313 14.5 Format strings 321 

14.2 Building Python extensions 316 14.6 Reference counts 324 

14.3 Using the Python API in 14.7 Embedding Python 325 
extensions 319 14.8 Summary 328 


14.4 Building extensions in C++ 320 


Python is readily extensible using a well-defined interface and build scheme. In this chapter, 
I will show you how to build interfaces to external systems as well as existing extensions. In 
addition, we will look at maintaining extensions from one Python revision to another. We'll 
also discuss the choice between embedding Python within an application or developing a 
freestanding Python application. 

The documentation that comes with Python is a good source of information on this 
topic, so this chapter will attempt not to repeat this information. My goal is to present the 
most important points so that you can easily build an interface. 


Writing a Python extension 


Many Python programmers will never have a need to extend Python; the available library 
modules satisfy a wide range of requirements. So, unless there are special requirements, the 
standard, binary distributions are perfectly adequate. 

In some cases, writing an extension in C or C++ may be necessary: 
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1 When computational demands (intensive numeric operations, for example) make 
Python code inefficient. 


2 Where access to third-party software is required. This might be through some API 
(Application Program Interface) or a more complex interface.* 


3 To provide access to legacy software which does not lend itself to conversion to Python. 


4 To control external devices through mechanisms similar to items 2 and 3 above. 





Note Writing an extension for Python means that you must have the full source for 

the Python interpreter and access to a C or C++ compiler (if you are going to 
work with Windows, I recommend that you use Microsoft’s Visual C++ version 5 or later). 
Unless you are going to interface a library API or have severe performance problems, you 
may wish to avoid building an extension altogether. See “Programming for performance” 
on page 348 for some ideas to improve the performance of Python code. 





Let’s begin by looking at a simple example which will link a C API to Python (we will look at 
C++ later). For the sake of simplicity, let’s assume that the API implements several statistical 
functions. One of these functions is to determine the minimum, average and maximum values 
within four supplied real numbers. From the Python code, we are going to supply the values 
as discrete arguments and return the result as a tuple. Don’t worry if this sounds like a trivial 
task for Python-this is just a simple example!. 

Here’s what we want to do from the Python side: 


import statistics 
minimum, average, maximum = statistics.mavm(1.3, 5.5, 6.6, 8.8) 


We start by creating the file statisticsmodule.c. The accepted naming-convention for exten- 
sion modules is modulemodule.c (this will be important later if we want to create dynamic 
loading modules). 

All extension modules must include the Python API by including Ppython.h. This also 
includes several standard C-include files such as stdio.h, string.h and stdlib.h. Then 
we define the C functions that will support our API. 

The source code will look something like this: 


statisticsmodule1.c 


#include "Python.h" o 

static PyObject * 

stats_mavm(self, args) -© 
PyObject *self, *args; © 





* Ifyou need to provide a Python interface to a library, you may wish to take a look at SWIG (See 
“SWIG” on page 625), which provides a very convenient way of building an interface. In some cases 
it is possible for SWIG to develop an interface from an include file alone. This obviously saves effort 
and time. 
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oo 


double value[4], total; 





double minimum = 1E32; 
double maximum = -1E32; 
int iy 


if (!PyArg_ParseTuple (args, "dddd", &value[0], &value[1], 
&value[2], &value[3])) 
return NULL; 


for (i=0; i<4; i++) 
{ 
if (value[i] < minimum 
minimum = value[i 


i 


maximum = value[i 


) 
] 
if (value[i] > maximum) 
] 
total = total + value[i 


l; 
} 


return Py_BuildValue("(ddd)", minimum, total/4, maximum) ; O 
} 
static PyMethodDef statistics_methods[] = { 
{"mavm", stats_mavm, METH _VARARGS, "Min, Avg, Max"}, 





{NULL, NULL} }; 


DL_EXPORT (void) 
initstatistics() 





Py_InitModule("statistics", statistics_methods) ; 





Code comments 

As mentioned earlier, all extension modules must include the Python API definitions. 

All interface items are Python objects, so we define the function to return a PyObject. 
Similarly, the instance and arguments, args, are PyObjects. 

The Python API provides a function to parse the arguments, converting Python objects into 
C entities: 


if (!PyArg_ParseTuple (args, "dddd", &value[0], &value[1], 
&value[2], &value[3])) 
return NULL; 


PyArg_ParseTuple parses the args object using the supplied format string. The avail- 
able options are explained in “Format strings” on page 321. Note that you must supply the 
address of the variables into which parsed values are to be placed. 

Here we process our data. As you will note, this is really difficult! 
In a manner similar to PyArg_ParseTuple, Py_Buildvalue creates Python objects from C 
entities. The formats have the same meaning. 

return Py_BuildValue("(ddd)", minimum, total/4, maximum) 


In this case, we create a tuple as our return object. 
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All interface modules must define a methods table, whose function is to associate Python func- 
tion names with their equivalent C functions 


static PyMethodDef statistics_methods[] = { 
{"mavm", stats_mavm, METH_VARARGS, "Min, Avg, Max"}, 
{NULL, NULL} }; 





METH_VARARGS defines how the arguments are to be presented to the parser. The docu- 
mentation field is optional. Notice the naming convention for the methods table. Although 
this can take any name, it is usually a good idea to follow the convention. 


The methods table must be registered with the interpreter in an initialization function. When 
the module is first imported, the initstatistics() function is called. 


DL_EXPORT(void) initstatistics() 
{ 


Py_InitModule("statistics", statistics_methods) ; 


Again, the naming convention must be followed, because Python will attempt to call 
initmodulename for each module imported. 


Building Python extensions 


Before you can use the Python extension, you have to compile and link it. Here, you have sev- 
eral choices, depending on whether the target system is UNIX or Windows (sorry, I am not 
covering Macintosh extensions). 

Basically, we can make the module a permanent part of the Python interpreter so that it 
is always available, or we can link it dynamically. Dynamic linking is not available on all sys- 
tems, but it works well for many UNIX systems and for Windows. The advantage to loading 
dynamically is that you do not need to modify the interpreter to extend Python. 


Linking an extension statically in UNIX 


Linking an extension statically in UNIX is quite simple to do. If you have not already config- 
ured and built Python, do so as described in “Building and installing Python, Tkinter” on 
page 610. Copy your module (in this case, statisticsmodule.c) to the Modules direc- 
tory. Then, add on line at the end of Modules/Setup. local (you may add some comments, 
too, if you wish): 


*static* 
statistics statisticsmodule.c 


If your module requires additional libraries, such as an API, add -1xxx flags at the end 
of the line. Note that the *static* flag is really only required if the preceding modules have 
been built as shared modules by including the *shared* flag. 

Now, simply invoke make in the top-level Python directory to rebuild the python exe- 
cutable in that directory. 
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Linking an extension statically in Windows 


Linking an extension statically in Windows is a little more involved than the case for UNIX, 
but it is quite easy if you follow the steps. If you have not yet built Python, do so as described 
in “Building and installing Python, Tkinter” on page 610. 

First, edit PC/config.c. You will find a comment: 


/* -- ADDMODULE MARKER 1 -- */ 
extern void PyMarshal_Init(); 
extern void initimp(); 

extern void initstatistics(); 
extern void initwprint(); 











Add an extern reference for the init function. Then locate the second comment: 


/* -- ADDMODULE MARKER 2 -- */ 
/* This module "lives in" with marshal.c */ 
{"marshal", PyMarshal_Init}, 
/* This lives it with import.c */ 
{"imp", initimp}, 
/* Statistics module (P-Tk-P) */ 
{"statistics", initstatistics}, 
/* Window Print module */ 
{"wprint", initwprint}, 














Add the module name and its init function. 
Next, edit Pc/python15.dsp. Near the end you should find an entry for typeob- 
ject.c: 





SOURCE=..\Objects\typeobject.c 

# End Source File 

# 

# Begin Source File 
SOURCE=..\Modules\statisticsmodule.c 
# End Source File 

# 

# Begin Source File 
SOURCE=..\Modules\wprintmodule.c 

# End Source File 











Insert the lines for statisticsmodule.c. 
Lastly, open the workspace PCbuild/pcbuild.dsw in VC++, select the appropriate con- 
figuration (see “Building and installing Python, Tkinter” on page 610) and build the projects. 


Building a dynamic module in UNIX 


There are several styles of generating dynamically-loadable modules. I’m just going to present a 
method that works for Solaris, but all UNIX systems derived from SVR4 should provide similar 
interfaces. All the work is done in the makefile, so no code changes should be needed. As with 
static linking, build and install Python first so that libraries and other such items are in place. 
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makefile_dyn 


SRCS= statisticsmodule.c 
CFLAGS= -DHAVE_CONFIG_H 
C= cc 


# Symbols used for using shared libraries 


SO= -SsOo 

LDSHARED= ld -G O 

OBJS= statisticsmodule.o 

PYTHON_INCLUDE= -I/usr/local/include/python1.5 \ [© 

-I/usr/local/lib/python1.5/config 

statistics: $(OBJS) 
$(LDSHARED) $(OBJS) 0 
-Bdynamic -o statisticsmodule.so 


statisticsmodule.o: statisticsmodule.c 
$(C) -c $(CFLAGS) $(PYTHON_INCLUDI 
statisticsmodule.c 





Gl 
= 





Code comments 


@ crtacs defines HAVE_CONFIG_H (among other things, this defines the mode of dynamic 
loading). Not all architectures need this, but define it anyway. 


@ LDSHARED defines the 14 command line needed to generate shared libraries. This will vary 
with different architectures. 


© = pyruon_incupe defines the path for Python.h and the installed config.h. 


© The target for the link might need libraries to be supplied for more complex modules. The 
-lxxx flags would be placed right after the $ (OBUS) . 





© The compile rule is quite simple; just add the CFLAGS and PYTHON_INCLUDE variables. 


14.2.4 Building a dynamic module in Windows 


Once again, building a dynamic module in Windows is quite involved. It does require you 
to edit some files which contain comments such as DO NOT EDIT, but despite that, it works! 
As with static linking, build and install Python first so that libraries and other such items are 
in place. 

First, create a directory in the top-level Python directory, at the same level as Modules, 
Parser and so on. Give it the same name as your module. 

Next, copy all of the files necessary to support your module into this directory; for our 
example, we need only statisticsmodule.c. 

Then, in the PC directory of the standard Python distribution, you will find a directory 
called example_nt. Copy example.def, example.dsp, example.dsw and example.mak 
into the module directory, renaming the files with your module name as the prefix. 

Edit each of these files, changing the references to example to your module name. You 
will need to make over 50 changes to the make file. As you make the changes, note the paths 
to the Python library (which is python15.1ib in this case). If this does not match your 
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installed library, the best way to correct it is to delete it from the project and then add it in 
again. 
Finally, select the Debug or Release configuration and then choose the Build menu option 


Build statistics.dll to build the dll. 


14.2.5 Installing dynamic modules 


To install dynamic modules, you can do one of three things. You can place the module.so or 
module.d11 anywhere that is defined in the PYTHONPATH environment variable, you may 
add its path into the sys.path list at runtime, or you may copy it into the installed .../ 
python/lib/lib-dynload directory. All three methods achieve the same effect, but I usually 
place dll files right with python.exe on Windows and I put .so files in 1ib-dynload for 
UNIX. You may make your own choice. 


14.2.6 Using dynamic modules 


There are no differences in the operation and use of modules that are linked statically with the 
interpreter and those that are linked dynamically. The only thing that you may experience is a 
error if you forget to put the files in the right directory or to add the path to PYTHONPATH! 


Python 1.5.2b2 (#17, Apr 7 1999, 13:25:13) [C] on sunos5 
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam 
>>> import statistics 

>>> statistics.mavm(1.3, 5.5, 6.6, 8.8) 

(1.3, 5.55, 8.8) 

>>> 


14.3. Using the Python API in extensions 


The mavm routine in the previous example is really rather tame. Let’s change the input to a list 
and perform the same operations on it. 


statisticsmodule2.c 


#include "Python.h" 


static PyObject * 
stats_mavm(self, args) 
PyObject *self, *args; 





double total = 0.0; 

double minimum = 1531; 

double maximum = -1E31; 

int i, len; 

PyObject *idataList = NULL; 

PyFloatObject *f = NULL; eo 
double df; 

if (!PyArg_ParseTuple (args, "O", &idataList) ) 0 


return NULL; 


/* check first to make sure we've got a list */ 
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if (!PyList_Check(idataList) ) 








{ 
PyErr_SetString (PyExc_TypeError, 
"input argument must be a list"); 
return NULL; 
} 
len = PyList_Size(idataList) ; O 


for (i=0; i<len; i++) 


{ 
f = (PyFloatObject *)PyList_GetItem(idataList, i); O 
df = PyFloat_AsDouble (f); O 
if (df < minimum) 
minimum = df; 
Prr E A eee Remaining code removed----------- 





Code comments 


We need to define a Python object for the list that is being passed in as an argument and a 
PyFloatObject (a subtype of PyObject) to receive the items in the list. 


We are now receiving a single object (as opposed to discrete values in the previous example). 


We check that the object is indeed a list. This actually introduces a shortcoming—we cannot 
pass a tuple containing the values. If there zs an error, we use PyErr_SetString to generate 





PyExc_TypeError with a specific error message. 
List objects have a length attribute, so we get it. 
We get each item in the list. 


For each item we convert the PyFloat to a C double. The rest of the code has been 
removed; you have seen it before. 


This example only scratches the surface of what can be done with the Python API. A good 
place to find examples of its use is in the Modules directory in the Python source. One reason 
that this topic is important is that Python is very good at creating and manipulating strings, 
especially if they involve lists, tuples, or dictionaries. A very realistic scenario is the ability to 
use Python to create such data structures and then to use use C to further process the entries, 
using API calls inside an iterator. In this way, C can provide the speed for critical operations 
and Python can provide the power to handle data succinctly. 


Building extensions in C++ 


Python is a C-based interpreter. Although it’s possible to adjust the source so that it would 
compile as C++, it would be a large undertaking. This means that calling C++ functions from 
this C base introduces some special problems. However, if you are able to link Python with 
the C++ compiler (linker), the problems are reduced. 

Clearly, many C++ class libraries can support Python systems. The trick is to leave Python 
essentially unchanged and provide a wrapper which gives access to the class library. If you can 
use dynamic linking for extension modules, this is quite a painless experience. If you must link 
statically, you may be facing some challenges. 
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Because of the great variability of each architecture’s C++ compilers, I am not going to 
try to provide a cookbook to solve the various problems. However, I am going to present some 
code fragments that have worked for Solaris. 

To get a module to compile with C++, you need to define the Python API as a C segment 
to the C++ compiler: 


extern "C" { 
#include "Python.h" 
} 


Then, the init function must be given the same treatment: 
extern "C" { 


DL_EXPORT (void) 
initstatistics() 





Py_InitModule("statistics", statistics_methods) ; 


14.5 Format strings 


Format strings provide a mechanism to specify the conversion of Python types passed as argu- 

ments to the extension routines. The items in the string must match, in number and type, the 

addresses supplied in the PyArg_ParseTuple() call. Although the type of the arguments is 
checked with the format string, the supplied addresses are not checked. Consequently, errors 
here can have a disastrous effect on your application. 

Since Python supports long integers of arbitrary length, it is possible that the values can- 
not be stored inc long integers; in all cases where the receiving field is too small to store 
the value, the most significant bits are silently truncated. 

The characters |, :, and ; have special meaning in format strings. 

"|" This indicates that the remaining arguments in the Python argument list are optional. 
The C variables corresponding to optional arguments must be initialized to their default 
value since PyArg_ParseTup1e leaves the variables corresponding to absent arguments 
unchanged. 

":" The list of format units ends here; the string after the colon is used as the function name 
in error messages. 

";" The list of format units ends here; the string after the colon is used as the error message 
instead of the default error message. 
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Table 14.1 Format strings for PyArg_ParseTuple( ) 





Format 








unit Python type C type Description 

s string char * Convert a Python string to a C pointer to a charac- 
ter string. The address you pass must be a char- 
acter pointer; you do not supply storage. The C 
string is null-terminated. The Python string may 
not contain embedded nulls and it cannot be 
None. If it does or is, a TypeError exception is 
raised. 

s# string char *, int Stores into two C variables, the first one being a 
pointer to a character string, the second one 
being its length. The Python string may have 
embedded nulls. 

Zz string or char * Similar to s, but the Python object may also be 

None None, in which case the C pointer is set to NULL. 

z# string or char *, int Similar to s#. 

None 

b integer char Convert a Python integer to a tiny int, stored in 
a C char. 

h integer short int Convert a Python integer to a C short int. 
integer int Convert a Python integer to a plain C int. 
integer long int Convert a Python integer to a C long int. 

G string of char Convert a Python character, represented as a 
length 1 string of length 1, to a C char. 

£ float float Convert a Python floating point number to a C 
float. 

d float double Convert a Python floating point number to a C 
double. 

D complex Py_complex Convert a Python complex number to a C 
Py_complex structure. 

O object PyObject * Store a Python object (without conversion) in a C 
object pointer. The C interface receives the actual 
object that was passed. The object's reference 
count is not increased. 

o! object typeobject, Store a Python object in a C object pointer. This is 

PyObject * similar to O, but it takes two C arguments: the 


first is the address of a Python-type object speci- 
fying the required type, and the second is the 
address of the C variable (of type PyObject *) 
into which the object pointer is stored. If the 
Python object does not have the required type, a 
TypeError exception is raised. 
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Table 14.1 


Format strings for PyArg_ParseTuple( ) (continued) 





Format 


unit Python type 


C type 


Description 





O& object function, 


variable 


S string PyStringObject * 


(items) sequence matching items 


Convert a Python object to a C variable through a 
converter function. This takes two arguments: 
the first is a function, the second is the address 
of a C variable (of arbitrary type), cast to void *. 
The converter function is called as follows: 
status = function(object, variable); 
where object is the Python object to be con- 
verted and variable is the void * argument 
that was passed to PyArg_ConvertTuple(). 


The returned status should be 1 for a successful 
conversion and 0 if the conversion has failed. If 
conversion fails, the function should raise an 
exception. 


Similar to O, but it expects that the Python object 
is a string object. It raises a TypeError excep- 
tion if the object is not a string object. 





The object must be a Python sequence whose 
length is the number of format units in items. The 
C arguments must correspond to the individual 
format units in items. Format units for sequences 
may be nested. 








To return values to the Python program that called the extension, we use 


Py_Buildvalue, which uses similar format strings to PyWArg_ParseTuple. Py_BuildValue 


has a couple of differences. First, the arguments in the call are values, not addresses. Secondly, 


it does not create a tuple unless there are two or more format units, or if you enclose the empty 


or single format unit in parentheses. 


Table 14.2 Format strings for Py_BuildValue() 








fia C type Python type Description 

s char * string Convert a null-terminated C string to a Python 
object. If the C string pointer is NULL, None is 
returned. 

s# char *, int string Convert a C string and its length to a Python 
object. If the C string pointer is NULL, the length 
is ignored and None is returned. 

Zz char * string or Same as "s". If the C string pointer is NULL, 

None None is returned. 
z# char *, int string or Same as "s#". If the C string pointer is NULL, 


None 





None is returned. 
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Table 14.2. Format strings for Py_BuildValue() (continued) 








Format Pik 

ae C type Python type Description 

i int integer Convert a plain C int to a Python integer 
object. 

b char integer Same as i. 

h short int integer Same as i. 

1 long int integer Convert a C long int to a Python integer 
object. 

c char string of Convert a C int representing a character to a 

length 1 Python string of length 1. 

d double float Convert a C double to a Python floating point 

number. 
float float Same as d. 

O PyObject * object Pass a Python object incrementing its reference 
count. If the object passed in is a NULL pointer, 
it is assumed that this was caused because the 
call producing the argument found an error and 
set an exception. Therefore, 

Py_BuildValue () will return NULL but it 
does not raise an exception. If no exception has 
been raised, PyExc_SystemError is set. 

S PyObject * object Same as O. 

N PyObject * object Similar to O, except that the reference count is 
not incremented. 

O& function, object Convert variable to a Python object through 

variable a converter function. The function is called with 
variable (which should be compatible with 
void *) as its argument and it should return a 
new Python object, or NULL if an error occurred. 

(items) matching items tuple Convert a sequence of C values to a Python 
tuple with the same number of items. 

[items] matching items list Convert a sequence of C values to a Python list 
with the same number of items. 

{items} matching items dictionary Converta sequence of C values to a Python dic- 


tionary. Each consecutive pair of C values adds 
one item to the dictionary, using the first value 
as the key and the second as the value. 





Reference counts 


You may have noticed a couple of mentions of reference counts in the previous format string 
descriptions: If you are new to Python, and especially if you are new to extension writing and 
the Python API, this may be an important area to study. 
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The Python documentation for extensions and the API provides an excellent picture of 
what is entailed, and you want to see a full explanation, I recommend that you study the 
Python documentation. 

Most API functions have a return value of type PyObject *. This is a pointer to an arbi- 
trary Python object. All Python objects have similar base behavior and may be represented by 
a single C type. You cannot declare a variable of type PyObject; you can only declare Pyob- 
ject * pointers to the actual storage. All pyobjects have a reference count. 

This is where we need to take special care! When an object’s reference count becomes 
zero, it will be deconstructed. If the object contains references to other objects, then their 
reference counts are decremented. If their reference count becomes zero, then they too will be 
deconstructed. 

Problems usually occur when the interface extracts an object from a list and then uses that 
reference for a while (or worse, passes the reference back to the caller). In a similar fashion, a 





Py_DECREF() call before passing data to the caller will result in disaster. 
The Python documentation recommends that extensions use the API functions that have 
a PyObject, PyNumber, PySequence or PyMapping prefix, since these operations always 





increment the reference count. It is the caller’s responsibility to call Py_DECREF() when no 
further reference is required. 

Here’s a general rule of thumb: If you are writing a Python extension and you repeatedly 
get a crash when you either return a value or exit your application, you’ve got the reference 
counts wrong. 


14.7 Embedding Python 


When it is necessary to add Python functionality to a C or C++ application, it is possible to 
embed the Python interpreter. This can be invaluable if you need to create Python objects 
within a C program or, perhaps, use dictionaries as a data structure. It is also possible to com- 
bine extending and embedding within the same application. 

The Python documentation provides full documentation for the API, and you should ref- 
erence this material for details. All you need to use the API is to call Py_Tnitialize() once 
from your application before using API calls. 

Once the interpreter has been initialized, you may execute Python strings using 
PyRun_SimpleString() or you may execute complete files with PyRun_SimpleFile(). 
Alternatively, you can use the Python API to exercise precise control over the interpreter. 

Here is a simple example that illustrates a way that Python functionality may be accessed 
from C. We will access a dictionary created using a simple Python script from C. This provides 
a powerful mechanism for C programs to perform hashed lookups of data without the need to 
implement specific code. Most of the code runs entirely in C code, which means that perfor- 
mance is good. 


#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 
#include "Python.h" 
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PyObject *rDict = NULL; /* Keep these global */ oe 


PyObject *instanceDict; 
/* 
RE Initializes the dictionary 
ae Returns TRUE if successful, FALS 
*f 
int 
initDictionary(char *name) 
{ 
PyObject *importModule; 
int retval = 0; 


E otherwise 





/* KKKKKKKKKKKKKKEKKK Initialize interpreter KEK KKK KKK KKKKKKKKKEK */ 


Py_Initialize(); 


/* Import a borrowed reference to the dict Module */ 
if ((importModule = PyImport_ImportModule("dict") ) ) [© 
{ 
/* Get a borrowed reference to the dictionary instance */ © 
if ((instanceDict = PyObject_CallMethod(importModule, "Dictionary", 
"s", name))) 
{ 
/* Store a global reference to the dictionary */ 
rDict = PyObject_GetAttrString(instanceDict, "dictionary") ; 
if (rDict != NULL) 
retval = 1; 
} 
else 
{ 
printf("Failed to initialize dictionary\n") ; 
} 
} 
else 
{ 
printf("import of dict failed\n"); 
} 
return (retval); 
} 
/* 


xe Finalizes the dictionary 
ae Returns TRUE 


= 
int 
exitDictionary (void) 
{ 
/* kkkkxkkkkkkkxkkkkkx*k Finalize interpreter kkkxkxkxkkkkkxkkkkkkkkxk */ 


Py_Finalize(); 
return (1); 

} 

/* 


ae Returns the information in buffer (which caller supplies) 


*/ 
void 
getInfo(char *who, char *buffer) 


{ 
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PyObject *reference; 
int birthYear; 

int deathYear; 
char *birthPlace; 
char *degree; 
*buffer = '\0'; 


if (rDict) 

{ 
if ((reference = PyDict_GetItemString( rDict, who ))) 
{ 


Q 


if (PyTuple_Check (reference) ) 
{ 


if (PyArg_ParseTuple(reference, "iiss", 
&birthYear, &deathYear, &birthPlace, &degree) ) 


sprintf (buffer, 
"Ss was born at %s in %d. His degree is in %s.\n", 
who, birthPlace, birthYear, degree) ; 
if (deathYear > 0) 
sprintf ((buffer+strlen(buffer)), 
"He died in %d.\n", deathYear) ; 
} 


} 
else 
strcpy (buffer, "No information\n") ; 
} 
return; 


} 


main() 

{ 
static char buf[256]; 
initDictionary("Not Used") ; 
getInfo ("Michael Palin", buf); 
printf (buf); 
getInfo ("Spiny Norman", buf); 
printf (buf); 
getInfo ("Graham Chapman", buf); 
printf (buf); 
exitDictionary(); 





Code comments 


@ This example is meant to represent a long-term lookup service, so we hang on to the refer- 
ences from call to call to reduce overhead. 

@ We import the module dict .py. The pyImport_ImportModule call is entirely analogous to 
the Python statement import dict. 

© We create an instance of the dictionary using PyObject_Cal1Method. Now, although instan- 
tiating a class is not really calling a method, Python’s implementation makes it a method call 
in effect. Here is the short Python module, dict.py: 
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class Dictionary: 
def __init__(self, name=None) : 
self.dictionary = { 











‘Graham Chapman': (1941, 1989, 'Leicester', 'Medicine'), 
‘John Cleese': (1939, -1, 'Weston-Super-Mare', 'Law'), 
'Eric Idle': (1943, -1, 'South Shields', 'English'), 
'Terry Jones': (1942, -1, 'Colwyn Bay', 'English'), 
"Michael Palin': (1943, -1, 'Sheffield', 'History'), 

'Terry Gilliam': (1940, -1, 'Minneapolis', 'Political Science'), 


} 
Then we get the reference to self.dictionary and store it for later use. 
PyDict_GetItemString(rDict, who) is equivalent to the statement: 
tuple = self.dictionary[who] 
This is a bit of paranoid code: we check that we really retrieved a tuple. 


Finally, we unpack the tuple using the format string. 
To compile and link you would use something like this (on Win32): 


cl -c dictionary.c -I\pystuff\python-1.5.2\Include \ 
-I\pystuff\python-1.5.2\PCc -I. 

link dictionary.obj \pystuff\python-1.5.2\PCbuild\pythoni5.lib \ 
-out:dict.exe 


If you run dict.exe, you'll see output similar to figure 14.1. 


cers 

jchael Palin was born at Sheffield in 1943. His degree is in History. 
No information. 
Graham Chapman was born at Leicester in 1941. His degree is in Medicine. 
He died in 1989. 


Figure 14.1 Python embedded in a C application 


Summary 


You may never need to build a Python extension or embed Python in an application, but in 
some cases it is the only way to interface with a particular system or develop code economi- 
cally. Although the information contained in this chapter is accurate at the time of writing, I 
suggest that you visit www.python.org to obtain information about the current release. 
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Debugging applications 


15.1 Why print statements? 329 15.5 pdb 336 
15.2 A simple example 330 15.6 IDLE 336 
15.3 How to debug 333 15.7 DDD 337 


15.4 A Tkinter explorer 334 


Debugging is a tricky area. I know that I’m going to get some stern comments from some of 
my readers, but Im going to make a statement that is bound to inflame some of them. 
Python is easy to debug if you insert print statements at strategic points in suspect code. 

Not that some excellent debug tools aren’t available, including IDLE, which is Python’s 
emerging IDE, but as we shall see later there are some situations where debuggers get in the 
way and introduce artifacts. 

In this chapter we will look at some simple techniques that really work and Pll offer some 
suggestions for readers who have not yet developed a method for debugging their applications. 


Why print statements? 


Debugging a simple Python program using a debugger rarely causes problems—you can 
happily single-step through the code, printing out data as changes are made, and you can 
make changes to data values to experiment with known values. When you are working with 
GUIs, networked applications or any code where timed events occur, it is difficult to predict 
the exact behavior of the application. This is why: for GUIs, a mainloop dispatches events in 
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a particular timing sequence; for network applications there are timed events (in particular, 
time-outs which may be short enough to occur while single-stepping). 

Since many of the applications that I have worked on have fallen into these categories, I 
have developed a method which usually avoids the pitfalls I have described. I say usually 
because even though adding print statements to an application only slightly increases the over- 
all execution time, it still has an effect on CPU usage, ouput either to a file or stdout and the 
overall size of the code. 

By all means try the tools that are available—they are very good. If you get results that 
have you totally confused, discouraged, or angry, try print statements! 


A simple example 


Many of the examples in this book use try ... except clauses to trap errors in execution. This 
is a good way of writing solid code, but it can make life difficult for the programmer if there 
are errors, since an error will cause Python to branch to the except section when an error 
occurs, possibly masking the real problem. 

Python has one downside to testing a program: even though the syntax may be correct 
when Python compiles to bytecode, it may not be correct at runtime. Hence we need to locate 
and fix such errors. I have doctored one of the examples used earlier in the book to introduce 
a couple of runtime errors. This code is inside a try ... except clause with no defined excep- 
tion; this is not a particularly good idea, but it does help the example, because it is really dif- 
ficult to find the location of the error. 

Let’s try running debug1.py: 


C:> python debugl.py 
An error has occurred! 


To add insult to injury, we still get part of the expected output, as shown in figure 15.1. 


Simple Plot - version 3 - Smoothed 


Figure 15.1 Debugging 
stage one 
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To start debugging, we have two alternatives: we can put print statements in the code 
to find out where we last executed successfully, or we can disable the try ... except. To do 


this, quickly edit the file like this: 


if 1: 
# try: 
#----------- Code removeđd------------------------------------------ 
# except: 
# print 'An error has occurred! ' 


Putting in the if 1: and commenting out the except clause means that you don’t have 
to redo the indentation—which would probably cause even more errors. Now, if you run 
debug2.py, you'll get the following result: 


C:> python debug2.py 
Traceback (innermost last): 
File "debug2.py", line 41, in ? 
main() 
File "debug2.py", line 23, in main 
canvas.create_line(100,y,105,y, width=2) 
NameError: y 


So, we take a look at the section of code and see the following: 


for i in range(6): 
x = 250 - (i + 40) 
canvas.create_line(100,y,105,y, width=2) 
canvas.create_text(96,y, text='%5.1f£'% (50.*i), anchor=E) 


Okay, it’s my fault! I cut and pasted some of the code and left x as the variable. So I'll 
change the x to y and reinstate the try ... except (that’s obviously the only problem!). 
Now, let’s run debug3.py: 


C:> python debug3.py 


No errors, but the screen is nothing like I expect—take a look at figure 15.2! Clearly the 
y-axis is not being created correctly, so let’s print out the values that are being calculated: 


for i in range(6): 
y = 250 - (i + 40) 
print "i=%d, y=%d" %(i, y) 
canvas.create_line(100,y,105,y, width=2) 
canvas.create_text(96,y, text='%5.1f£'% (50.*i), anchor=E) 


Now run debug4.py: 


python debug4.py 
, y=210 
, y=209 
y=208 
1 y=207 
1 y=206 
, y=205 
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Simple Plot - Yersion 3 - Smoothed 


Figure 15.2 Debugging 
stage two 


That’s not what I meant! Decrementing 1 pixel at a time will not work!. If you look at 


the line of code before the print statement, you will see that I meant to multiply by 40 not 
just add 40. So let’s make the changes and run debug5.py: 


C:> python debug5.py 


No errors, again, but not the result I expected (see figure 15.3) the “blobs” are supposed 


to be on the line. Let’s look at the bit of code that’s supposed to plot the points: 


scaled = [] 
for x,y in [(12, 56), (20, 94), (33, 98), (45, 120), (61, 180), 
(75, 160), (98, 223)]: 
scaled.append(100 + 3*x, 250 - (4*y)/5) 


Simple Plot - Version 3 - Smoothed 


Figure 15.3 Debugging, 
stage three 
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That looks Okay, but let’s check it out: 


scaled = [] 
for x,y in [(12, 56), (20, 94), (33, 98), (45, 120), (61, 180), 
(75, 160), (98, 223)]: 
s = 100 + 3*x, 250 - (4*y)/5 
print "x,y = %d,%d" % (s[0], s[1]) 
scaled.append (s) 


Now, run debug6.py: 


C:> python debug6.py 
x,y - 136,206 

x,y - 160,175 

x,y - 199,172 

x,y - 235,154 

x,y - 283,106 

x,y - 325,122 

x,y - 394,72 


Yes, that looks right (blast!). We need to look further: 


canvas.create_line(scaled, fill='black', smooth=1) 


for xs,ys in scaled: 
canvas.create_oval (x-6,y-6,x+6,y+6, width=1, 
outline='black', fill='SkyBlue2') 


Pll save you any more pain on this example. Obviously it was contrived and I’m not usu- 
ally so careless. I meant to use xs and ys as the scaled coordinates, but I used x and y in the 
canvas .create_oval method. Since I had used x and y earlier, I did not get a NameError, 
so we just used the /ast values. I’m sure that you will take my word that if the changes are made, 
the code will now run! 


15.3 How to debug 


The ability to debug is really as important as the ability to code. Some programmers have real 
problems in debugging failing code, particularly when the code is complex. The major skill in 
debugging is to ignore the unimportant and focus on the important. The secondary skill is to 
learn how to gain the major skill. 

Really, you want to confirm that the code is producing the values you expect and follow- 
ing the paths you expect. This is why using print statements (or using a debugger where 
appropriate) to show the actual values of variables, pointers and the like is a good idea. Also, 
putting tracers into your code to show which statements are being executed can quickly help 
you focus on problem areas. 

If you are proficient with an editor such as emacs it is really easy to insert debugging statements 
into your code. If you have the time and the inclination, you can build your code so that it is ready 
to debug. Add statements which are only executed when a variable has been set. For example: 


if debug > 2: 
print (‘location: var=%d, var2=%s’ % (var, var2) 
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Clearly, you could add more detail, timestamps and other data that may help you if you 
encounter problems when you start running your code. Planning for the need to debug is often 
easier at the time you write the code than when you have pressure to deliver. 


A Tkinter explorer 


In “Building an application” on page 18 I suggested a technique for hiding access to a debug 
window. This often works well, since you have immediate access to the tool, usually without 
restarting the application. I’m including an example here (the code is available online) which 
pops up if an error is output to stderr. Then you can look at the source, change variables in 
the namespace or even launch another copy of the application to check it out. Here are a 
series of screenshots: 









= 


Disable 








‘af | | 


e valid here 






~ 


Open... | Save... | Clear AT Ta 











Exception in Tkinter callback 
Traceback (innermost last): 


File "C:\PYTHON\Iib\lib-tk\Tkinter.py", 1 7 
return apply(self.func, args) B1 | B2 | B3 | B4 | 


File “buggy.py", line 46, in disable 
self.B2.configure(state=DISABLED, bac 

File “C:\PYTHON\lib\lib-tk\Tkinter.py", | Disable | Enable | Focus | 
self.tk.call((self._w, ‘configure') 


TelError: unknown color name “cadetblue< Tabs are valid here 


Quit | 













Print 






Figure 15.4 An embedded debug tool 
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Then, open up the source in the top window and look for the error: 


Tkinter Explorer 
frame3.pack(fill=x, expand=1) 
self.dbg=DBG(master, popup=1) 
def disable(self): 
self.B2.configure(state=DISABLED, background='cac *tblue42') 
self.Focus.configure(state=DISABLED, background="‘\ 3detblue') 


def enable(self): 
self.B2.configure(state=NORMAL, background=self.B1.cget(‘backgro 


Save... || Clear LETETT ELT 


Exception in Tkinter callback 
Traceback (innermost last): 
File "C:\PYTHON\lib\lib-tk\ Tkinter.py", line 764, in__call__ 
return apply(self.func, args) 
File "buggy.py", line 46, in disable 
self.B2.configure(state=DISABLED, background='cadetblue42') 
File "C:\PYTHON\lib\lib-tk\ Tkinter.py", line 623, in 
self.tk.call((self._w, 'configure’) 
TclError: unknown color name "cadetblue42" 


Talila stdout/stderr output 


Figure 15.5 Locating the 
code error 





If we correct the error and then click Run, we execute another copy of the application and 
we can see that the problem has been corrected. The window at the top-left-hand corner of 
figure 15.6 shows how this looks. 


lol 


aE aK 


Tabs are valid here 


def disable(self): 
self.B2.configure(state=DISABLED, background='cadetblue') 
self.Focus.configure(state=DISABLED, background='cadetblue') 


def enable(self): 
self.B2.configure(state=NORMAL, background=self.B1.cget('backgro 


X 


Save... | Clear Interpreter input 


File "C:\PYTHON\lib\lib-tk\Tkinter.py", line 764, in __call__ 
) 


self.B2.configure(state=DISABLED, backgrot ra 
File "C:\PYTHON\lib\lib-tk\ Tkinter.py", line 6: 


Fl 
reitshcaiccatt— E ed 


Tabs are valid here 


aut | 


Figure 15.6 Executing a second version of the application 
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15.5 pdb 


If you like to type, this is the debug tool for you! pdb is a basic debugger that will allow you to 
set breakpoints, get data values and examine the stack, to name but a few of its facilities. Its 
drawback is that you have to input a lot of data to get to a particular point of interest and 
when the time comes to do it again, you have to enter the information again! 

This tool isn’t for everyone, but if your debug style fits pdb, then it will probably work for you. 


15.6 IDLE 


IDLE is an emerging IDE for Python. It has some limitations which will reduce as time goes 
by and its usage increases. You can already see demands for various types of functionality on 
the Python news group. This will continue to grow as more users find out what is needed in 
the tool. Make sure that you obtain the latest code rather than using the code packaged in 
Python 1.5.2—many changes and bug fixes have been made recently. 

I have included a screenshot of an IDLE session to give you an idea of what is provided. 
Try the tool and decide if it will meet your expectations. 




















ell* Simple Plot - Version 3 - Smoothed 
Debug } 





File Edit 






d M Stack M Source 
Python 1.5.2 (#0, Go | Step | Over | out | aut | 
Copyright 1991-199 I Locas M Globals 
>>> 
DEBUG ON. $ 1224: 
I9 at debugex TEE AE EREE) 
[DEBUG ON] 


>>> debugexample.m 
2 e |_console__. line 1: debugexample.main{) 


debugexample. main(), line 16: canvas. create_line(x,250,x,245, width=2) 
Pees ee eel ae eee eee te ee Pees 


















debugexample. py 
File Edit Windows cnt = {} 


- return getintCapplyc 
From Tkinter import * self.tk.call, 





(self._w, ‘create’, itemType) 
def main): + args + self._options(cnf, kw))) 
root = Tk() c create_arc(self, *args, **kw): 












root.title('Simple Plot - Ver return self._create('arc', args, kw) 
create_bitmap(self, *args, **kw): 
‘, args, kw) 














canvas = Canvas(root, width=« 
canvas. pack() 

Button(root, text='Quit', cor 
canvas. create_line(100,250, 4¢ return self._create('line’, args, kw) 
canvas .create_line(100,250,1¢ c create_oval(self, *args, **kw): 

return self._create('oval', args, kw) 
for i in range(11): c create_polygon(self, *args, **kw): 

x = 100 + (i * 30) return self._create('polygon', args, kw) 
canvas.create_line(x,250, Create_rectangle(self, *args, **kw): 

canvas. create_text(x,254. return self._create('rectangle', args, kw) 
create_text(self, *args, **kw): 

for i in range(é): return self._create('text', args, kw) 
y= 250 - (i * 40) c create_window(self, *args, **kw): 
canvas.create_line(100,y, return self._create('window', args, kw) 
canvas. create_text(96,y, dchars(self, *args): 




























at 7e45b0> 












scaled = [] 

for x,y if [(12, 56), (20, 94), (33, 98), (45, 120), (61, 180), 
(75, 160), (98, 223)]: 

scaled.append(100 + 3*x, 250 - (4*y)/5) 











canvas.create_line(scaled, fill='black', smooth=1) 
EXCEPTION 


EXTENDED ‘extended’ 
EllipsisType <type ‘ellipsis'> 
Entry <class Tkinter. Entry at 7e9360> = 







Tor x,y in scaled: 
canvas .create_oval (x-6,y-6,x+6,y+6, width=1, 
outline='black', fill='SkyBlue2') 








root.mainloop() 


Figure 15.7 Debugging with IDLE 


336 CHAPTER 15 DEBUGGING APPLICATIONS 











15.7 DDD 


DDD isa graphic front-end debugger for a number of languages. It uses a modified version of 
pdb and has a wide range of support from programmers. Again, I have included an example 
session, and I leave it to you to decide if it will be useful to you! 





cobj + coaptle(petr. “inline’. “exec”) 
exec (e0d$) 


Gravinterval + 1000*se)f 
ane. after (deawtnter 











Figure 15.8 Debugging with DDD 
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Designing effective 
graphics applications 


16.1 The elements of good interface 16.3 Alternative graphical user 
design 339 interfaces 346 
16.2 Human factors 342 16.4 Summary 347 


A graphical user interface has become an expected part of most applications which have 
direct communication with users. This chapter describes the essentials of good GUI 
design—but keep in mind that this area is highly subjective, of course. Some consider- 
ations of font and color schemes will be covered, along with size, ergonomic and other 
human factors. Finally, alternatives for GUI design will be suggested, introducing photo- 
realism, virtual reality and other emerging techniques. 

Established standards for interface design are noted in the bibliography. Many com- 
panies have internal design standards which may be in conflict with established standards; 
the life of a GUI programmer is not always easy and aesthetics may succumb to standards 
in some cases. 

If one thing should be selected as the major determinant of good GUI design, it is 
probably simplicity. An elegant interface will display the minimum information necessary 
to guide the user into inputting data and observing output. As we shall see, there may be 
cases where a little added complexity enhances an interface, but in general, keep it simple. 
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16.1 The elements of good interface design 


User interfaces are really rather simple: display a screen, have 
the user input data and click on a button or two and show the 
user the result of their actions. This appears to be easy, but 


unless you pay attention to detail, the end user’s satisfaction 
My Street 


with the application can be easily destroyed by a badly 
designed GUI. Of course, appreciation of GUI’s is highly 


= subjective and it is almost impossible to satisfy everyone. We 
01234 


My City 


are going to develop a number of example interfaces in this 
(401) 555-1212 


ena bose chapter and examine their relative merits. The source code for 
12345 the examples will not be presented in the text, but it is avail- 


123-45-6789 





able online if you want to reproduce the examples or use 





them as templates for your own interfaces. You can see many 
more examples of Tkinter code throughout the book! If you 
do use the supplied source code, please make sure that only 
the good examples are used. 

Take a look at the first GUI (figure 16.1). You may not believe me, but I have seen GUIs 
similar to this one in commercial applications. This screen does all that it is intended to do—and 





Figure 16.1 An inferior 
interface 


nothing more—but without any concern for the end user or for human factors. You may wish 
to examine this example again after we have discussed how to construct a better GUI. 

Even though I said that this is an inferior GUI, this type of screen can be acceptable in 
certain contexts; if all that is needed is a simple screen to input debug information for an appli- 
cation, the amount of code necessary to support this screen is quite small. However, don’t 
inflict this type of screen on an end user; especially if they are expected to pay money for it! 

So let’s take a quick look at the screen’s faults before we determine how the screen could 
be improved. 


1 Jagged label/entry boundary is visually taxing, causing the user to scan randomly in the 
GUI. 

2 Poor choice of font: Courier is a fixed pitch serif font. In this case it does not have suffi- 
cient weight or size to allow easy visual scanning. 

3 Although the contrast between the black letters and the white background in the entry 
fields is good, the contrast between the frame and the label backgrounds is too great and 
makes for a stark interface. 


4 Crowded fields make it difficult for the user to locate labels and fields. 


5 Fields have arbitrary length. This provides no clues to the user to determine the length of 
data that should be input. 

6 Poor grouping of data: the Position, Employee # type of data have more to do with the 
name of the individual than the address of the individual and should be grouped 
accordingly. 


Let’s attempt to correct some of the problems with figure 16.1 and see if we can improve 
the interface. Figure 16.2 shows the result of changing some of the attributes of the GUI. 
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1 This interface uses the grid manager; the previ- 
ous interface used the pack manager (see 
“Grid” on page 86 for details of the geometry 
managers). This has corrected the jagged align- 
ment of the labels and fields. 


2 The font has been changed to a larger sans serif 
font which improves readability when com- 
pared to the previous example, but see “Choos- 


CU ing fonts” on page 343. 


3 The background color of the entry fields has 
been changed to narrow the contrast between 


the labels and fields. 


4 A small amount of padding has been applied 
around the fields to make scanning easier. 


123-45-6789 





A 
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Figure 16.2 A better interface 


The interface is better, but it can still be improved more. Arranging the fields in logical 
groups and setting the size of some of the fields to an appropriate width will assist the user to 
fill in the information. Also, grouping some of the fields on the same line will result in a less 
vertically-linear layout, which fits scan patterns better since we tend to scan horizontally better 
than we scan vertically—that is how we learned to read, after all. This may not apply to cultures 
where printed characters are read vertically, however. 

The next example implements the points discussed above. 

The GUI in figure 16.3 is beginning to show signs of improvement since the fields are 
grouped logically and the width of the entries matches the data widths that they support. The 
Position entry has been replaced by a ComboBox (a Pmw widget) which allows the user to select 
from a list of available options (see figure 16.4). 


— 
e Boss x 
401) 555-1212 
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Figure 16.3 A GUI showing logical 
field grouping 





We can improve the interface further by breaking appropriate fields into subfields. For 
example, social security numbers always have a 3-2-4 format. We can handle this situation in 
two ways: 

1 Use three separate fields for each of the subfields. 


2 Use a smart widget that automatically formats the data to insert the hyphens in the data. 
Smart widgets are discussed in “Formatted (smart) widgets” on page 117. 
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The Boss 





Figure 16.4 ComboBox widget 


Figure 16.5 shows our example with the fields split into appropriate subfields. 

Unfortunately, this change has now cluttered our interface and the composition is now 
rather confusing to the end user. We have to make a further adjustment to separate the logical 
field groups and to help the user to navigate the interface. In figure 16.6, we introduce 
whitespace between the three groups. 


eS es 


Figure 16.5 Splitting fields into 
sub-fields 





This achieves the desired effect, but we can improve the effect further by drawing a 
graphic around each of the logical groups. This can be achieved in a number of ways: 


1 Use available 3-D graphic relief options with containers. Tkinter frames allow sunken, 
raised, groove and ridge, for example. 


2 Draw a frame around the group. This is commonly seen in Motif GUIs, usually with an 
accompanying label in the frame. 


3 Arrange for the background color of the exterior of the frame to be displayed in a differ- 
ent color from the inside of the frame. Note that this kind of differentiation is suitable 
for only a limited range of interface types. 
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Figure 16.6 Separating logical groups 
with whitespace 
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Figure 16.7 illustrates the application of a 3-D graphic groove in the frame surrounding 


the grouped fields. 





amemo 


Figure 16.7 Logical groups framed 
with a 3-D graphic 





16.2 Human factors 


Extensive documents on Human Factor Engineering describe GUI design in scientific terms 
(see the Reference section). In particular, font choice may be based on calculating the arc sub- 
tended by a character from a point 20 inches from the character (the viewing position). While 
I have worked on projects where it was necessary to actually measure these angles to confirm 
compliance with specifications, it is not usually necessary to be so precise. 

When designing an application that includes a GUI, you should consider the following 
human factors: 


1 Ensure that the application meets the end users expectations. If a paper system is cur- 
rently being used, the GUI application should mimic at least some of that operation, for 
example. 


2 Keep the interface simple and only request necessary data from the user; accordingly, 
only display pertinent data. 


3 Select fonts that make the interface work effectively. Use as few different fonts as possi- 
ble within a single screen. 


4 Lay out the information in a logical sequence, grouping areas where appropriate, so that 
the user is led through the information in a smooth fashion, not jumping between key 
areas. 


5 Use color sparingly and to achieve a specific purpose. For example, use color to highlight 
fields that must be entered by the user as opposed to optional fields. 


6 Provide multiple navigation methods in the GUI. It is not always appropriate to require 
navigation to be mouse-based; tabbing from field to field within a form may be more 
natural to users than clicking on each field to enter data. Provide both so the user may 
choose. 


7 Ensure consistency in your application. Function keys and control-key combinations 
should result in similar actions throughout a single application and between applications 
in a suite. 
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16.2.1 


8 Some platforms may have GUI style guides that constrain the design. These should be 
adhered to, even if it means developing platform-specific versions. 


9 Provide help wherever possible. Balloon help* can be useful for beginning users but may 
be annoying to experts. Consequently it is important to provide the user with a means of 
turning off such facilities. 


10 The UI should be intuitive so that it is not necessary to provide documentation. Careful 
field labeling, clues to input format and clear validation schemes can go a long way to 
achieve this goal. 


n Whenever possible, test the UI with end users. Building prototypes in Python is easy, so 
take advantage of this and get feedback from the target audience for your work. 


Choosing fonts 


Choosing an appropriate font for a GUI is important to ensure that an interface is effective. 
Readability is an important factor here. A font that is highly readable when displayed at a 
screen resolution of 640 x 480 may be too small to read when displayed at a resolution of 
1024 x 768 or greater. The size of the font should, therefore, be either calculated based on the 
screen resolution or selected by the end user. However, in the latter case, you should ensure 
that the end user is given a range of fonts that the application can display without changing 
screen layouts or causing overflows, overlaps or other problems. 

Font selection can be crucial to achieving an effective interface. In general, serif t fonts 
should be avoided. Most of us are used to reading serif fonts on printed material (in fact, the 
body of this book is set in Adobe Garamond, a font with a light serif) since we believe that we 
are able to recognize word forms faster in serif as opposed to 